smart_brain 0.1.2 → 0.3.0

data/examples/README.md

@@ -0,0 +1,49 @@
+# SmartBrain 示例集
+
+每个脚本都是**自包含、可独立运行**的，从易到难、按需引入外部依赖。
+全部默认零外部依赖即可起步；PG / Ollama / SmartRAG 按场景按需开启。
+
+## 场景速查
+
+| 脚本 | 场景 | 依赖 | 后端 |
+|---|---|---|---|
+| [`01_memory_basic.rb`](01_memory_basic.rb) | 最小闭环：commit→compose→search→brief→diagnostics | 无 | memory |
+| [`02_governance.rb`](02_governance.rb) | 记忆治理：lifecycle + KG + fact_check + brief | 无 | memory |
+| [`03_postgres_persistence.rb`](03_postgres_persistence.rb) | 跨「重启」持久化召回 | PostgreSQL | postgres |
+| [`04_ollama_llm.rb`](04_ollama_llm.rb) | LLM 真摘要 + rerank | Ollama | memory |
+| [`05_smart_rag_integration.rb`](05_smart_rag_integration.rb) | 对话记忆 + 资源 RAG 融合 | SmartRAG | memory |
+| [`06_multi_scope_memory.rb`](06_multi_scope_memory.rb) | project/task 跨会话共享、冲突与 promotion | 无 | memory |
+
+## 运行
+
+```bash
+cd /root/smart_brain
+
+ruby examples/01_memory_basic.rb            # 直接跑，无需任何配置
+ruby examples/02_governance.rb              # 直接跑
+
+SMARTBRAIN_DB_NAME=smart_brain_test \
+  ruby examples/03_postgres_persistence.rb  # 需先建库（见脚本顶部注释）
+
+ruby examples/04_ollama_llm.rb              # 需 ollama serve + ollama pull llama2
+SMARTBRAIN_LLM_MODEL=qwen3 ruby examples/04_ollama_llm.rb   # 换更强的模型（更慢）
+
+SMARTBRAIN_RAG_DB_HOST=... SMARTBRAIN_RAG_DB_NAME=smart_rag_development \
+  ruby examples/05_smart_rag_integration.rb # 需 SmartRAG 实例
+  ruby examples/06_multi_scope_memory.rb
+```
+
+> 没装对应依赖时，03/04/05 会**打印设置步骤并优雅退出**（不会崩）。
+
+## 阅读顺序建议
+
+1. `01_memory_basic.rb` —— 先建立 commit/compose 心智模型。
+2. `02_governance.rb` —— 理解「记忆宫殿」的分层与生命周期。
+3. 按需挑 03/04/05 之一看持久化、LLM、资源检索如何接入。
+
+## 参考文档
+
+- 完整用法：[`../docs/user_guide.md`](../docs/user_guide.md)
+- MCP 接入：[`../docs/mcp.md`](../docs/mcp.md)
+- 设计与契约：`../docs/smartbrain_design.md`、`../docs/memory_types.md`、`../docs/policies.md`
+- 完整 SmartRAG 集成 demo：`../conversation_demo.rb`、`../example.rb`

data/exe/smart_brain

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SmartBrain CLI — drive the memory runtime from the shell or as an agent tool.
+#
+#   smart_brain status
+#   smart_brain migrate                         (postgres backend only)
+#   smart_brain commit   --data '{"session_id":..,"turn_events":{..}}'
+#   smart_brain compose  --data '{"session_id":..,"user_message":..}'
+#   smart_brain search   --data '{"session_id":..,"query":..}'
+#   smart_brain serve    [--host 0.0.0.0] [--port 9292] [--config PATH]
+#   smart_brain mcp      [--config PATH]        (stdio JSON-RPC, for Claude Code / Cursor)
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'optparse'
+require 'json'
+require 'smart_brain'
+require 'smart_brain/server/service'
+require 'smart_brain/server/http_app'
+require 'smart_brain/server/mcp_server'
+
+module SmartBrain
+  module CLI
+    module_function
+
+    def run(argv)
+      config_path = ENV['SMARTBRAIN_CONFIG']
+      global = OptionParser.new do |opts|
+        opts.banner = 'Usage: smart_brain <command> [options]'
+        opts.on('--config PATH', 'Path to brain.yml') { |p| config_path = p }
+        opts.on('--version', 'Print version and exit') { puts SmartBrain::VERSION; exit 0 }
+        opts.on('-h', '--help', 'Show this help') { puts opts; exit 0 }
+      end
+      global.order!(argv)
+
+      command = argv.shift
+      abort(global.to_s) unless command
+
+      case command
+      when 'status'  then print_json(Server::Service.build(config_path: config_path).status)
+      when 'migrate' then print_json(ok: Server::Service.build(config_path: config_path).migrate)
+      when 'commit', 'compose', 'search', 'fact-check', 'brief', 'wake-up'
+        data_cmd(command, argv, config_path)
+      when 'knowledge' then knowledge_cmd(argv, config_path)
+      when 'kg' then kg_cmd(argv, config_path)
+      when 'serve'   then serve(argv, config_path)
+      when 'mcp'     then mcp(config_path)
+      else
+        warn "unknown command: #{command}"
+        warn global.to_s
+        exit 1
+      end
+    end
+
+    def data_cmd(command, argv, config_path)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end
+      parser.parse!(argv)
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case command
+        when 'commit' then service.commit(**payload.slice(:domain_id, :session_id, :scope_context, :turn_events).merge(turn_events: payload[:turn_events] || {}))
+        when 'compose' then service.compose(**payload.slice(:domain_id, :session_id, :scope_context, :user_message, :agent_state).merge(agent_state: payload[:agent_state] || {}))
+        when 'search' then service.search(**payload.slice(:domain_id, :session_id, :scope_context, :query, :limit))
+        when 'fact-check' then service.fact_check(**payload.slice(:domain_id, :session_id, :scope_context, :text))
+        when 'brief' then service.brief(**payload.slice(:domain_id, :session_id, :scope_context, :query))
+        when 'wake-up' then service.wake_up(**payload.slice(:domain_id, :session_id, :scope_context))
+        end
+      print_json(result)
+    end
+
+    def knowledge_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      action = argv.shift
+      abort 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'distill' then service.distill(**payload.slice(:domain_id, :session_id, :scope_context, :statement, :content, :tier, :supporting_refs, :domain, :field, :reviewer, :key))
+        when 'gate' then service.gate(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'promote' then service.promote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer, :force))
+        when 'demote' then service.demote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reason_type, :reviewer))
+        when 'retract' then service.retract(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reviewer))
+        when 'promote-to-scope' then service.promote_to_scope(**payload.slice(:memory_item_id, :target_scope, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer))
+        when 'lineage' then service.promotion_lineage(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'events' then service.knowledge_events(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        else abort "unknown knowledge action: #{action}"
+        end
+      print_json(result)
+    rescue SmartBrain::Governance::LifecycleGateError, ArgumentError => e
+      warn "#{e.class}: #{e.message}"
+      exit 1
+    end
+
+    def kg_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+      action = argv.shift
+      abort 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'add' then service.kg_add(**payload.slice(:domain_id, :session_id, :scope_context, :scope_ref, :subject, :predicate, :object, :confidence, :source_turn_id))
+        when 'query' then service.kg_query(**payload.slice(:domain_id, :session_id, :scope_context, :subject, :predicate, :object, :include_invalid))
+        when 'timeline' then service.kg_timeline(**payload.slice(:domain_id, :session_id, :scope_context, :subject))
+        when 'invalidate' then service.kg_invalidate(**payload.slice(:edge_id, :reason, :domain_id, :session_id, :scope_context))
+        when 'stats' then service.kg_stats(**payload.slice(:domain_id, :session_id, :scope_context))
+        else abort "unknown kg action: #{action}"
+        end
+      print_json(result)
+    end
+
+    def serve(argv, config_path)
+      options = { host: '127.0.0.1', port: 9292 }
+      OptionParser.new do |opts|
+        opts.on('--host HOST') { |h| options[:host] = h }
+        opts.on('--port PORT', Integer) { |p| options[:port] = p }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      service = Server::Service.build(config_path: config_path)
+      Server::HttpApp.service = service
+      warn "[smart_brain] HTTP on http://#{options[:host]}:#{options[:port]} (backend: #{service.backend})"
+      Server::HttpApp.run!(host: options[:host], port: options[:port], server: :puma) do |server|
+        # Puma-specific tuning can go here.
+      end
+    end
+
+    def mcp(config_path)
+      service = Server::Service.build(config_path: config_path)
+      Server::McpServer.new(service: service).run
+    end
+
+    def read_payload(raw)
+      return {} if raw.nil? && $stdin.tty?
+      raw ||= $stdin.read
+      raw.to_s.strip.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError => e
+      abort "invalid JSON payload: #{e.message}"
+    end
+
+    def print_json(payload)
+      puts JSON.generate(payload)
+    end
+  end
+end
+
+SmartBrain::CLI.run(ARGV)

data/lib/smart_brain/adapters/smart_rag/direct_client.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class DirectClient
-        def initialize(rag:)
+        include ScopeFilter
+
+        def initialize(rag:, scope_mapper: nil, fail_closed: true)
           @rag = rag
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
         end
 
         def retrieve(plan)
-          response = rag.retrieve(plan: plan)
-          normalize_pack(response, request_id: plan[:request_id])
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          response = rag.retrieve(plan: scoped_plan)
+          pack = normalize_pack(response, request_id: plan[:request_id])
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue StandardError => e
           {
             version: '0.1',
@@ -24,9 +34,50 @@ module SmartBrain
           }
         end
 
+        def add_document(source, options = {}) = write(:add_document, source, options)
+        def add_media(source, options = {}) = write(:add_media, source, options)
+        def add_image(source, options = {}) = write(:add_image, source, options)
+        def add_audio(source, options = {}) = write(:add_audio, source, options)
+        def add_video(source, options = {}) = write(:add_video, source, options)
+        def enqueue_media(source, options = {}) = write(:enqueue_media, source, options)
+
+        def media_job(job_id)
+          rag.media_job(job_id) || { status: 'not_found', job_id: job_id, warnings: ['media job not found'] }
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id, warnings: ["smart_rag direct media_job failed: #{e.message}"] }
+        end
+
+        def media_jobs(status: nil, limit: 20, offset: 0)
+          rag.media_jobs(status: status, limit: limit, offset: offset)
+        end
+
+        def cancel_media_job(job_id) = rag.cancel_media_job(job_id)
+        def retry_media_job(job_id) = rag.retry_media_job(job_id)
+        def media_job_statistics = rag.media_job_statistics
+
         private
 
-        attr_reader :rag
+        attr_reader :rag, :scope_mapper, :fail_closed
+
+        def write(operation, source, options)
+          normalize_write_result(rag.public_send(operation, source, options), operation)
+        rescue StandardError => e
+          {
+            status: 'failed',
+            media_type: operation.to_s.delete_prefix('add_'),
+            section_count: 0,
+            warnings: ["smart_rag direct #{operation} failed: #{e.message}"]
+          }
+        end
+
+        def normalize_write_result(response, operation)
+          result = response.is_a?(Hash) ? response.dup : {}
+          result[:status] ||= 'success'
+          result[:media_type] ||= operation.to_s.delete_prefix('add_') unless operation == :add_media
+          result[:section_count] ||= 0
+          result[:warnings] = Array(result[:warnings])
+          result
+        end
 
         def normalize_pack(response, request_id:)
           pack = response.is_a?(Hash) ? response : {}
@@ -38,7 +89,8 @@ module SmartBrain
             evidences: Array(pack[:evidences]),
             stats: pack[:stats] || { candidates: Array(pack[:evidences]).size, returned: Array(pack[:evidences]).size, took_ms: 0 },
             explain: pack[:explain] || { ignored_fields: [] },
-            warnings: Array(pack[:warnings])
+            warnings: Array(pack[:warnings]),
+            scope_filter_applied: pack[:scope_filter_applied] == true
           }
         end
       end

data/lib/smart_brain/adapters/smart_rag/http_client.rb

@@ -1,18 +1,85 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class HttpClient
-        def initialize(transport:, timeout_seconds: 2)
+        include ScopeFilter
+
+        def initialize(transport:, write_transport: nil, job_transport: nil, job_list_transport: nil,
+                       job_mutation_transport: nil, job_statistics_transport: nil,
+                       timeout_seconds: 2, scope_mapper: nil, fail_closed: true)
           @transport = transport
+          @write_transport = write_transport
+          @job_transport = job_transport
+          @job_list_transport = job_list_transport
+          @job_mutation_transport = job_mutation_transport
+          @job_statistics_transport = job_statistics_transport
           @timeout_seconds = timeout_seconds
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
+        end
+
+        def self.for_url(base_url:, timeout_seconds: 30, headers: {}, scope_mapper: nil, fail_closed: true)
+          require_relative 'http_transport'
+          http_transport = HttpTransport.new(base_url: base_url, headers: headers)
+          new(
+            transport: http_transport.method(:retrieve),
+            write_transport: http_transport.method(:write),
+            job_transport: http_transport.method(:media_job),
+            job_list_transport: http_transport.method(:media_jobs),
+            job_mutation_transport: http_transport.method(:mutate_media_job),
+            job_statistics_transport: http_transport.method(:media_job_statistics),
+            timeout_seconds: timeout_seconds,
+            scope_mapper: scope_mapper,
+            fail_closed: fail_closed
+          )
+        end
+
+        def add_document(source, options = {}) = write(:add_document, source, options)
+        def add_media(source, options = {}) = write(:add_media, source, options)
+        def add_image(source, options = {}) = write(:add_image, source, options)
+        def add_audio(source, options = {}) = write(:add_audio, source, options)
+        def add_video(source, options = {}) = write(:add_video, source, options)
+        def enqueue_media(source, options = {}) = write(:add_media, source, options.merge(async: true))
+
+        def media_job(job_id)
+          return { status: 'unsupported', job_id: job_id, warnings: ['smart_rag job transport not configured'] } unless job_transport
+          result = job_transport.call(job_id, timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue Timeout::Error
+          { status: 'failed', job_id: job_id, warnings: ['smart_rag media_job timeout'] }
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id, warnings: ["smart_rag media_job failed: #{e.message}"] }
+        end
+
+        def media_jobs(status: nil, limit: 20, offset: 0)
+          call_job_transport(job_list_transport, { status: status, limit: limit, offset: offset }, fallback: { jobs: [], total: 0 })
+        end
+
+        def cancel_media_job(job_id)
+          call_job_mutation(job_id, :cancel)
+        end
+
+        def retry_media_job(job_id)
+          call_job_mutation(job_id, :retry)
+        end
+
+        def media_job_statistics
+          call_job_transport(job_statistics_transport, fallback: { counts: {}, total: 0 })
         end
 
         def retrieve(plan)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          raw = transport.call(plan, timeout_seconds: timeout_seconds)
-          build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          raw = transport.call(scoped_plan, timeout_seconds: timeout_seconds)
+          pack = build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue Timeout::Error
           {
             version: '0.1',
@@ -28,7 +95,52 @@ module SmartBrain
 
         private
 
-        attr_reader :transport, :timeout_seconds
+        attr_reader :transport, :write_transport, :job_transport, :job_list_transport,
+                    :job_mutation_transport, :job_statistics_transport, :timeout_seconds,
+                    :scope_mapper, :fail_closed
+
+        def call_job_transport(callable, argument = nil, fallback:)
+          return fallback.merge(status: 'unsupported', warnings: ['smart_rag job transport not configured']) unless callable
+          result = argument ? callable.call(argument, timeout_seconds: timeout_seconds) : callable.call(timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue StandardError => e
+          fallback.merge(status: 'failed', warnings: ["smart_rag media job request failed: #{e.message}"])
+        end
+
+        def call_job_mutation(job_id, action)
+          return { status: 'unsupported', job_id: job_id,
+                   warnings: ['smart_rag job transport not configured'] } unless job_mutation_transport
+          result = job_mutation_transport.call(job_id, action, timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id,
+            warnings: ["smart_rag media job request failed: #{e.message}"] }
+        end
+
+        def write(operation, source, options)
+          return unsupported_write(operation) unless write_transport
+
+          raw = write_transport.call(
+            { operation: operation, source: source, options: options },
+            timeout_seconds: timeout_seconds
+          )
+          result = raw.is_a?(Hash) ? raw.dup : {}
+          result[:status] ||= 'success'
+          result[:section_count] ||= 0
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue Timeout::Error
+          { status: 'failed', section_count: 0, warnings: ["smart_rag #{operation} timeout"] }
+        rescue StandardError => e
+          { status: 'failed', section_count: 0, warnings: ["smart_rag #{operation} failed: #{e.message}"] }
+        end
+
+        def unsupported_write(operation)
+          { status: 'unsupported', section_count: 0,
+            warnings: ["smart_rag write transport not configured; #{operation} ignored"] }
+        end
 
         def build_pack(raw:, request_id:, took_ms:)
           ignored = []
@@ -48,7 +160,8 @@ module SmartBrain
             explain: {
               ignored_fields: ignored + Array(raw.dig(:explain, :ignored_fields))
             },
-            warnings: Array(raw[:warnings])
+            warnings: Array(raw[:warnings]),
+            scope_filter_applied: raw[:scope_filter_applied] == true
           }
         end
 

data/lib/smart_brain/adapters/smart_rag/http_transport.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+
+module SmartBrain
+  module Adapters
+    module SmartRag
+      class HttpTransport
+        EXTRACTOR_OPTIONS = %i[
+          audio_transcriber video_transcriber image_describer frame_describer ocr_extractor
+        ].freeze
+
+        def initialize(base_url:, headers: {})
+          @connection = Faraday.new(url: base_url, headers: headers) do |faraday|
+            faraday.request :multipart
+            faraday.request :url_encoded
+            faraday.adapter Faraday.default_adapter
+          end
+        end
+
+        def retrieve(plan, timeout_seconds:)
+          response = connection.post('/v1/retrieve') do |request|
+            request.options.timeout = timeout_seconds
+            request.headers['Content-Type'] = 'application/json'
+            request.body = JSON.generate(plan: serializable(plan))
+          end
+          parse_response(response)
+        end
+
+        def write(payload, timeout_seconds:)
+          options = payload.fetch(:options, {})
+          reject_callable_options!(options)
+          source = payload.fetch(:source).to_s
+
+          response = if File.file?(source)
+                       upload_file(payload[:operation], source, options, timeout_seconds)
+                     else
+                       write_source(payload[:operation], source, options, timeout_seconds)
+                     end
+          parse_response(response)
+        end
+
+        def media_job(job_id, timeout_seconds:)
+          response = connection.get("/v1/media/jobs/#{Integer(job_id)}") do |request|
+            request.options.timeout = timeout_seconds
+          end
+          parse_response(response)
+        end
+
+        def media_jobs(params, timeout_seconds:)
+          response = connection.get('/v1/media/jobs', params) { |request| request.options.timeout = timeout_seconds }
+          parse_response(response)
+        end
+
+        def mutate_media_job(job_id, action, timeout_seconds:)
+          response = connection.post("/v1/media/jobs/#{Integer(job_id)}/#{action}") do |request|
+            request.options.timeout = timeout_seconds
+          end
+          parse_response(response)
+        end
+
+        def media_job_statistics(timeout_seconds:)
+          response = connection.get('/v1/media/jobs/stats') { |request| request.options.timeout = timeout_seconds }
+          parse_response(response)
+        end
+
+        private
+
+        attr_reader :connection
+
+        def upload_file(operation, source, options, timeout_seconds)
+          connection.post('/v1/media') do |request|
+            request.options.timeout = timeout_seconds
+            request.body = {
+              operation: operation.to_s,
+              options: JSON.generate(serializable(options)),
+              file: Faraday::Multipart::FilePart.new(source, mime_type(source), File.basename(source))
+            }
+          end
+        end
+
+        def write_source(operation, source, options, timeout_seconds)
+          connection.post('/v1/media') do |request|
+            request.options.timeout = timeout_seconds
+            request.headers['Content-Type'] = 'application/json'
+            request.body = JSON.generate(
+              operation: operation.to_s, source: source, options: serializable(options)
+            )
+          end
+        end
+
+        def reject_callable_options!(options)
+          unsupported = EXTRACTOR_OPTIONS.select do |key|
+            value = options[key] || options[key.to_s]
+            value.respond_to?(:call) || value.respond_to?(:extract)
+          end
+          return if unsupported.empty?
+
+          raise ArgumentError,
+                "HTTP media ingestion cannot serialize extractors: #{unsupported.join(', ')}; configure them on SmartRAG"
+        end
+
+        def serializable(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(key, item), result| result[key] = serializable(item) }
+          when Array
+            value.map { |item| serializable(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+
+        def parse_response(response)
+          body = JSON.parse(response.body, symbolize_names: true)
+          return body if response.success?
+
+          raise "SmartRAG HTTP #{response.status}: #{body[:error] || response.reason_phrase}"
+        rescue JSON::ParserError
+          raise "SmartRAG HTTP #{response.status}: invalid JSON response"
+        end
+
+        def mime_type(path)
+          extension = File.extname(path).downcase
+          {
+            '.jpg' => 'image/jpeg', '.jpeg' => 'image/jpeg', '.png' => 'image/png',
+            '.wav' => 'audio/wav', '.mp3' => 'audio/mpeg', '.mp4' => 'video/mp4',
+            '.pdf' => 'application/pdf', '.txt' => 'text/plain', '.md' => 'text/markdown'
+          }.fetch(extension, 'application/octet-stream')
+        end
+      end
+    end
+  end
+end