hindsight-ruby 0.1.0

data/lib/hindsight/types/fact.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'payload'
+
+module Hindsight
+  module Types
+    class Fact
+      attr_reader :text, :type, :entities, :occurred_at, :context, :metadata, :raw
+
+      def initialize(text:, type: nil, entities: [], occurred_at: nil, context: nil, metadata: {}, raw: nil)
+        @text = text.to_s
+        @type = type&.to_sym
+        @entities = normalize_entities(entities)
+        @occurred_at = coerce_time(occurred_at)
+        @context = context
+        @metadata = metadata || {}
+        @raw = raw || {}
+      end
+
+      def self.from_api(payload)
+        raw = payload || {}
+        return new(text: raw.to_s, raw: {}) unless raw.is_a?(Hash)
+
+        value = Payload.stringify_keys(raw)
+
+        new(
+          text: value['text'] || value['content'],
+          type: value['type'] || value['kind'],
+          entities: value['entities'] || [],
+          occurred_at: value['occurred_at'],
+          context: value['context'],
+          metadata: value['metadata'] || {},
+          raw: value
+        )
+      end
+
+      def inspect
+        truncated = text.length > 60 ? "#{text.slice(0, 60)}..." : text
+        "#<#{self.class} text=#{truncated.inspect} type=#{type.inspect} entities=#{entities.inspect}>"
+      end
+
+      def to_s
+        text
+      end
+
+      def to_h
+        {
+          text: text,
+          type: type,
+          entities: entities,
+          occurred_at: occurred_at,
+          context: context,
+          metadata: metadata
+        }
+      end
+
+      private
+
+      def coerce_time(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def normalize_entities(value)
+        Array(value).map do |entity|
+          entity.is_a?(Hash) ? Payload.stringify_keys(entity) : entity.to_s
+        end
+      end
+    end
+  end
+end

data/lib/hindsight/types/operation_receipt.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'payload'
+require_relative '../errors'
+
+module Hindsight
+  module Types
+    class OperationReceipt
+      attr_reader :operation_ids, :raw, :bank
+
+      def initialize(operation_ids:, raw: nil, bank: nil)
+        @operation_ids = Array(operation_ids).map(&:to_s)
+        @raw = raw || {}
+        @bank = bank
+      end
+
+      def inspect
+        "#<#{self.class} operation_ids=#{operation_ids.inspect}>"
+      end
+
+      def to_s
+        operation_ids.join(', ')
+      end
+
+      def self.from_api(payload = nil, bank: nil)
+        body = Payload.stringify_keys(payload || {})
+        operation_ids = body['operation_ids'] || Array(body['operation_id']).compact
+        new(operation_ids: operation_ids, raw: body, bank: bank)
+      end
+
+      def submitted?
+        operation_ids.any?
+      end
+
+      def operation_id
+        operation_ids.first
+      end
+
+      def fetch(bank: nil)
+        resolved_bank = resolve_bank(bank)
+        operation_ids.map { |id| resolved_bank.operations.get(id) }
+      end
+
+      def wait(bank: nil, interval: 1.0, timeout: 120.0)
+        resolved_bank = resolve_bank(bank)
+        resolved_bank.operations.wait(operation_ids, interval: interval, timeout: timeout)
+      end
+
+      def to_h
+        { operation_ids: operation_ids }
+      end
+
+      private
+
+      def resolve_bank(bank)
+        resolved_bank = bank || @bank
+        return resolved_bank if resolved_bank
+
+        raise ValidationError, 'bank is required when receipt was not created from a bank-scoped operation'
+      end
+    end
+  end
+end

data/lib/hindsight/types/operation_status.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'payload'
+
+module Hindsight
+  module Types
+    class OperationStatus
+      TERMINAL_STATES = %i[completed failed cancelled error].freeze
+      SUCCESS_STATES = %i[completed].freeze
+      FAILURE_STATES = %i[failed cancelled error].freeze
+
+      attr_reader :id, :status, :error, :result, :raw
+
+      def initialize(id:, status:, error: nil, result: nil, raw: nil)
+        @id = id.to_s
+        @status = status.to_sym
+        @error = error
+        @result = result
+        @raw = raw || {}
+      end
+
+      def terminal?
+        TERMINAL_STATES.include?(status)
+      end
+
+      def successful?
+        SUCCESS_STATES.include?(status)
+      end
+
+      def failed?
+        FAILURE_STATES.include?(status)
+      end
+
+      def inspect
+        "#<#{self.class} id=#{id.inspect} status=#{status.inspect}>"
+      end
+
+      def to_s
+        "#{id}: #{status}"
+      end
+
+      def to_h
+        { id: id, status: status, error: error, result: result }
+      end
+
+      def self.from_api(payload = nil, operation_id: nil)
+        body = Payload.stringify_keys(payload || {})
+        id = operation_id || body['operation_id'] || body['id']
+        status = body['status'] || 'unknown'
+        error = body['error']
+        result = body['result']
+
+        new(id: id, status: status, error: error, result: result, raw: body)
+      end
+    end
+  end
+end

data/lib/hindsight/types/payload.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Hindsight
+  module Types
+    module Payload
+      module_function
+
+      def stringify_keys(value)
+        h = value || {}
+        raise ValidationError, 'payload must be a Hash' unless h.is_a?(Hash)
+
+        deep_stringify(h)
+      end
+
+      def deep_stringify(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            result[key.to_s] = deep_stringify(item)
+          end
+        when Array
+          value.map { |item| deep_stringify(item) }
+        else
+          value
+        end
+      end
+
+      private_class_method :deep_stringify
+    end
+  end
+end

data/lib/hindsight/types/recall_result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'payload'
+require_relative 'fact'
+
+module Hindsight
+  module Types
+    class RecallResult
+      include Enumerable
+
+      attr_reader :facts, :token_count, :query, :budget, :raw
+
+      def initialize(facts:, token_count: nil, query: nil, budget: nil, raw: nil)
+        @facts = Array(facts)
+        @token_count = token_count
+        @query = query
+        @budget = budget&.to_sym
+        @raw = raw || {}
+      end
+
+      def inspect
+        parts = ["facts=#{facts.size}", ("token_count=#{token_count}" if token_count), "query=#{query.inspect}"]
+        "#<#{self.class} #{parts.compact.join(' ')}>"
+      end
+
+      def to_s
+        facts.map(&:to_s).join("\n")
+      end
+
+      def each(&block)
+        facts.each(&block)
+      end
+
+      def empty?
+        facts.empty?
+      end
+
+      def to_h
+        { facts: facts.map(&:to_h), token_count: token_count, query: query, budget: budget }
+      end
+
+      def self.empty(query: nil, budget: nil)
+        new(facts: [], token_count: 0, query: query, budget: budget, raw: {})
+      end
+
+      def self.from_api(payload = nil, query: nil, budget: nil)
+        body = Payload.stringify_keys(payload || {})
+        facts_payload = body['facts'] || body['memories'] || body['results'] || []
+        token_count = body['token_count'] || body.dig('usage', 'total_tokens')
+
+        facts = Array(facts_payload).map { |item| Fact.from_api(item) }
+
+        new(
+          facts: facts,
+          token_count: token_count,
+          query: query || body['query'],
+          budget: budget || body['budget'],
+          raw: body
+        )
+      end
+    end
+  end
+end

data/lib/hindsight/types/reflection.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'payload'
+require_relative 'fact'
+
+module Hindsight
+  module Types
+    class Reflection
+      attr_reader :raw, :text, :data
+
+      def initialize(raw: nil, text: nil, based_on: [], data: nil)
+        @raw = raw || {}
+        @text = text
+        @raw_based_on = based_on
+        @data = data
+      end
+
+      def based_on
+        @based_on ||= Array(@raw_based_on).map { |fact| Fact.from_api(fact) }
+      end
+
+      def self.from_api(payload)
+        body = Payload.stringify_keys(payload || {})
+        text = body['text'] || body['answer'] || body['reflection']
+        based_on = body['based_on'] || body['facts'] || []
+        data = body['structured_output'] || body['data'] || body['json']
+
+        new(raw: body, text: text, based_on: based_on, data: data)
+      end
+
+      def inspect
+        truncated = text && text.length > 60 ? "#{text.slice(0, 60)}..." : text
+        "#<#{self.class} text=#{truncated.inspect} based_on=#{based_on.size}>"
+      end
+
+      def to_s
+        text.to_s
+      end
+
+      def to_h
+        { text: text, based_on: based_on.map(&:to_h), data: data }
+      end
+
+      def json
+        data
+      end
+    end
+  end
+end

data/lib/hindsight/upload_normalizer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "errors"
+
+module Hindsight
+  module UploadNormalizer
+    CONTENT_TYPES = {
+      ".pdf" => "application/pdf",
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif",
+      ".webp" => "image/webp",
+      ".mp3" => "audio/mpeg",
+      ".wav" => "audio/wav",
+      ".m4a" => "audio/mp4",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    }.freeze
+
+    module_function
+
+    # Normalize file entries into upload hashes suitable for multipart upload.
+    # When +allowed_paths+ is set, path-based entries are restricted to those
+    # directories (symlinks are resolved via File.realpath before checking).
+    def normalize_uploads(files, allowed_paths: nil)
+      entries = (files.is_a?(Array) ? files : [files]).flatten.compact
+      raise ValidationError, "files must contain at least one entry" if entries.empty?
+
+      closers = []
+      begin
+        uploads = entries.map do |entry|
+          normalize_upload(entry, closers, allowed_paths: allowed_paths)
+        end
+        [uploads, closers]
+      rescue StandardError
+        closers.each do |io|
+          io.close unless io.closed?
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+    end
+
+    def normalize_upload(entry, closers, allowed_paths: nil)
+      case entry
+      when String, Pathname
+        ensure_allowed_paths_present!(allowed_paths)
+        build_upload_from_path(entry, closers, allowed_paths: allowed_paths)
+      when Hash
+        build_upload_from_hash(entry)
+      else
+        raise ValidationError,
+          "Invalid file entry: #{entry.inspect}. Expected path string, Pathname, or upload hash"
+      end
+    end
+
+    def build_upload_from_path(path_like, closers, allowed_paths: nil)
+      path = File.realpath(path_like.to_s)
+      validate_path_allowed!(path, path_like, allowed_paths) if allowed_paths
+      raise ValidationError, "Path for retain_files is not a regular file: #{path_like.inspect}" unless File.file?(path)
+      raise ValidationError, "File not readable for retain_files: #{path_like.inspect}" unless File.readable?(path)
+      filename = sanitize_multipart_value(File.basename(path))
+      raise ValidationError, "Invalid filename for retain_files: #{path_like.inspect}" if filename.empty?
+
+      io = File.open(path, "rb")
+      closers << io
+      {
+        io: io,
+        filename: filename,
+        content_type: content_type_for_filename(path)
+      }
+    rescue Errno::ENOENT
+      raise ValidationError, "File not found for retain_files: #{path_like.inspect}"
+    rescue Errno::EACCES
+      raise ValidationError, "File not readable for retain_files: #{path_like.inspect}"
+    end
+
+    def build_upload_from_hash(entry)
+      io = entry[:io] || entry["io"]
+      filename = entry[:filename] || entry["filename"]
+      content_type = entry[:content_type] || entry["content_type"] || content_type_for_filename(filename)
+
+      raise ValidationError, "Invalid upload hash: missing :io" unless io.respond_to?(:read)
+      raise ValidationError, "Invalid upload hash: missing :filename" if filename.to_s.strip.empty?
+
+      sanitized_filename = sanitize_multipart_value(filename)
+      raise ValidationError, "Invalid upload hash: empty :filename after sanitization" if sanitized_filename.empty?
+
+      sanitized_content_type = sanitize_multipart_value(content_type)
+      raise ValidationError, "Invalid upload hash: empty :content_type after sanitization" if sanitized_content_type.empty?
+
+      {
+        io: io,
+        filename: sanitized_filename,
+        content_type: sanitized_content_type
+      }
+    end
+
+    def ensure_allowed_paths_present!(allowed_paths)
+      return unless allowed_paths.nil?
+
+      raise ValidationError,
+        "Path uploads require allowed_paths to be set. " \
+        "Use upload hashes ({io:, filename:, content_type:}) when you intentionally need unrestricted IO."
+    end
+
+    def validate_path_allowed!(resolved, original, allowed_paths)
+      dirs = normalize_allowed_paths(allowed_paths)
+      return if dirs.any? { |dir| resolved.start_with?("#{dir}/") || resolved == dir }
+
+      raise ValidationError,
+        "Path #{original.inspect} resolves to #{resolved.inspect} which is outside allowed_paths"
+    end
+
+    def normalize_allowed_paths(allowed_paths)
+      Array(allowed_paths).map.with_index do |dir, index|
+        path = dir.to_s.strip
+        raise ValidationError, "allowed_paths[#{index}] must be a non-empty path" if path.empty?
+
+        begin
+          File.realpath(path)
+        rescue Errno::ENOENT
+          File.expand_path(path)
+        rescue ArgumentError, SystemCallError
+          raise ValidationError, "Invalid allowed_paths[#{index}]: #{dir.inspect}"
+        end
+      end
+    end
+
+    def sanitize_multipart_value(value)
+      value.to_s.gsub(/[\r\n\0"]/, "").strip
+    end
+
+    def content_type_for_filename(filename)
+      CONTENT_TYPES.fetch(File.extname(filename.to_s).downcase, "application/octet-stream")
+    end
+  end
+end

data/lib/hindsight/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hindsight
+  VERSION = '0.1.0'
+end

data/lib/hindsight-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "hindsight"

data/lib/hindsight.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'hindsight/version'
+require_relative 'hindsight/errors'
+require_relative 'hindsight/option_validation'
+require_relative 'hindsight/client'
+require_relative 'hindsight/resources/base'
+require_relative 'hindsight/resources/banks'
+require_relative 'hindsight/resources/memories'
+require_relative 'hindsight/resources/mental_models'
+require_relative 'hindsight/resources/directives'
+require_relative 'hindsight/resources/chunks'
+require_relative 'hindsight/resources/documents'
+require_relative 'hindsight/resources/entities'
+require_relative 'hindsight/resources/operations'
+require_relative 'hindsight/resources/observations'
+require_relative 'hindsight/resources/tags'
+require_relative 'hindsight/resources/config'
+require_relative 'hindsight/resources/graph'
+require_relative 'hindsight/upload_normalizer'
+require_relative 'hindsight/bank'
+require_relative 'hindsight/types/payload'
+require_relative 'hindsight/types/fact'
+require_relative 'hindsight/types/recall_result'
+require_relative 'hindsight/types/reflection'
+require_relative 'hindsight/types/operation_receipt'
+require_relative 'hindsight/types/operation_status'
+
+module Hindsight
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: hindsight-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrey Samsonov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Framework-agnostic ruby client for Hindsight APIs.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- hindsight-ruby.gemspec
+- lib/hindsight-ruby.rb
+- lib/hindsight.rb
+- lib/hindsight/bank.rb
+- lib/hindsight/client.rb
+- lib/hindsight/errors.rb
+- lib/hindsight/option_validation.rb
+- lib/hindsight/resources/banks.rb
+- lib/hindsight/resources/base.rb
+- lib/hindsight/resources/chunks.rb
+- lib/hindsight/resources/config.rb
+- lib/hindsight/resources/directives.rb
+- lib/hindsight/resources/documents.rb
+- lib/hindsight/resources/entities.rb
+- lib/hindsight/resources/graph.rb
+- lib/hindsight/resources/memories.rb
+- lib/hindsight/resources/mental_models.rb
+- lib/hindsight/resources/observations.rb
+- lib/hindsight/resources/operations.rb
+- lib/hindsight/resources/tags.rb
+- lib/hindsight/types/fact.rb
+- lib/hindsight/types/operation_receipt.rb
+- lib/hindsight/types/operation_status.rb
+- lib/hindsight/types/payload.rb
+- lib/hindsight/types/recall_result.rb
+- lib/hindsight/types/reflection.rb
+- lib/hindsight/upload_normalizer.rb
+- lib/hindsight/version.rb
+homepage: https://github.com/kryzhovnik/hindsight-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kryzhovnik/hindsight-ruby
+  bug_tracker_uri: https://github.com/kryzhovnik/hindsight-ruby/issues
+  changelog_uri: https://github.com/kryzhovnik/hindsight-ruby/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Standalone Hindsight API client for Ruby
+test_files: []