hindsight-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 532ef9d4f663621fe910acdf0935a53b1983df34d9cb8300dd47cdcda8eee7da
+  data.tar.gz: 2aaa1601db930922f22ddd43494385e5cb92b8a78d2bff40f9a521ad8add8ea8
+SHA512:
+  metadata.gz: 1c6d5db1e4d4965e64e1cdb5e0effbcb27f825730b72d1bc3bde64be3a816d4d37d7d549d68ea5c00d74a4cc4169e9967b64b1cf21e7e4ec9653df791f905e91
+  data.tar.gz: 4062a35309f63312689cff818437d28281e741729730271d28006239f45b97a4188c6048c146ad9aaccf3183d5f727cb3973b75dea328c89c6e357ba2e35d380

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andrey Samsonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,325 @@
+# hindsight-ruby
+
+`hindsight-ruby` is a standalone, framework-agnostic Ruby client for the [Vectorize Hindsight](https://github.com/vectorize-io/hindsight) API.
+
+It provides a small Ruby-idiomatic API for:
+
+- retaining text memories
+- retaining files for async processing
+- polling async operation status
+- recalling facts
+- reflecting over stored memory
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'hindsight-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require 'hindsight-ruby'
+
+client = Hindsight::Client.new('http://localhost:8888')
+bank = client.bank('quick-start')
+
+bank.retain('The team is shipping v2.0 by end of March')
+bank.retain('Maria is on vacation March 20-31')
+bank.retain('Maria is the only one certified for production deploys')
+
+# Recall: parallel retrieval (semantic, keyword, graph, temporal) — no LLM
+result = bank.recall('shipping schedule')
+result.facts.each { |f| puts "- #{f.text}" }
+
+# Reflect: agentic multi-step search across topics, then synthesizes — uses LLM
+reflection = bank.reflect('What are the risks to the v2.0 launch?')
+puts reflection.text
+
+client.banks.delete('quick-start')
+```
+
+## API
+
+### `Hindsight::Client`
+
+```ruby
+client = Hindsight::Client.new(
+  'https://hindsight.example.com',
+  api_key: ENV['HINDSIGHT_API_KEY'], # optional
+  headers: { 'X-Request-Source' => 'my-app' }, # optional
+  logger: Logger.new($stdout), # optional Faraday response logger
+  # connection: my_faraday, # optional; inject a pre-configured Faraday connection
+  # allow_insecure: true, # optional, only if you intentionally send credentials over non-localhost http://
+  open_timeout: 2,
+  timeout: 10
+)
+```
+
+If `api_key` is provided, the client sends:
+
+```http
+Authorization: Bearer <api_key>
+```
+
+`connection:` is mainly useful for tests or advanced Faraday customization. If provided, the client uses it directly instead of building an internal connection.
+
+When credentials are configured (`api_key` or `Authorization` header), non-localhost `http://` base URLs are rejected unless `allow_insecure: true` is explicitly set.
+
+Methods:
+
+- `client.bank(bank_id)`
+- `client.banks` (resource API for bank containers)
+- `client.chunks` (resource API for chunk retrieval)
+- `client.version`
+- `client.health`
+- `client.features`
+- `client.file_upload_api_supported?`
+
+### `Hindsight::Bank`
+
+#### Retain text
+
+```ruby
+bank.retain(
+  'User prefers vegetarian restaurants',
+  context: 'chat',
+  tags: ['diet'],
+  document_id: 'msg-123',
+  timestamp: '2026-03-01T10:00:00Z',
+  metadata: { 'source' => 'slack' },
+  entities: [{ text: 'Alice', type: 'person' }],
+  document_tags: ['onboarding'],
+  async: false
+)
+```
+
+The client sends retain payloads to `POST /memories`.
+
+Return value:
+
+- when `async: true`, returns `Hindsight::Types::OperationReceipt` (poll with `#fetch` / `#wait`)
+- when `async: false` (or omitted), returns the raw API response hash
+
+#### Retain batch
+
+```ruby
+receipt = bank.retain_batch(
+  [
+    { content: 'Alice likes coffee', context: 'chat', tags: ['prefs'] },
+    { content: 'Bob likes tea', metadata: { 'source' => 'email' } }
+  ],
+  document_tags: ['import'],
+  async: true
+)
+```
+
+`retain_batch` follows the same return contract as `retain`: `async: true` returns `OperationReceipt`; `async: false` returns the raw API response hash.
+
+#### Retain files
+
+```ruby
+receipt = bank.retain_files(
+  ['/tmp/profile.pdf'],
+  context: 'chat',
+  tags: ['onboarding'],
+  files_metadata: [{ context: 'report', document_id: 'doc-1' }],
+  allowed_paths: ['/tmp']
+)
+
+puts receipt.operation_ids.inspect
+```
+
+`retain_files` returns `Hindsight::Types::OperationReceipt`.
+
+`retain_files` raises `Hindsight::FeatureNotSupported` when the server reports `file_upload_api: false`.
+
+**Security:** For path entries, `retain_files` requires `allowed_paths:` and resolves paths with `File.realpath` (resolving symlinks and requiring the target to exist). Do not pass user-controlled paths directly. If you need custom unrestricted file handles, pass upload hashes (`{ io:, filename:, content_type: }`) instead of paths.
+
+#### Poll operation status
+
+```ruby
+# Poll each operation id once
+statuses = receipt.fetch
+
+# Wait until all operations become terminal (completed/failed/cancelled/etc)
+final_statuses = receipt.wait(interval: 1.0, timeout: 120.0)
+
+final_statuses.each do |status|
+  puts "#{status.id} status=#{status.status} done=#{status.terminal?} ok=#{status.successful?}"
+end
+```
+
+`receipt.fetch(bank: other_bank)` and `receipt.wait(bank: other_bank, ...)` are also supported if you want to override the bank context explicitly.
+
+You can also call polling APIs directly:
+
+```ruby
+status = bank.operations.get('op-123')
+done = bank.operations.wait(%w[op-123 op-456], interval: 0.5, timeout: 60, backoff: :exponential, max_interval: 30)
+```
+
+#### Recall
+
+```ruby
+result = bank.recall(
+  'What are dietary preferences?',
+  budget: :mid,
+  max_tokens: 2048,
+  types: [:world] # optional: :world, :experience, :observation
+)
+
+result.facts.each do |fact|
+  puts [fact.text, fact.type, fact.entities].inspect
+end
+
+puts result.token_count
+```
+
+Returns `Hindsight::Types::RecallResult` (Enumerable).
+
+#### Reflect
+
+```ruby
+reflection = bank.reflect(
+  'Summarize this user',
+  budget: :high
+)
+
+puts reflection.text
+```
+
+Returns `Hindsight::Types::Reflection`.
+
+Optional advanced controls:
+
+```ruby
+reflection = bank.reflect(
+  'Summarize this user',
+  include: { facts: { max_count: 8 }, tool_calls: { input: false, output: false } },
+  response_schema: {
+    type: 'object',
+    properties: { summary: { type: 'string' } },
+    required: ['summary']
+  }
+)
+
+puts reflection.json.inspect
+```
+
+#### Additional endpoints
+
+The gem exposes client-level and bank-level endpoints through resource objects:
+
+```ruby
+# bank containers (client-level)
+client.banks.list
+client.banks.create(bank_id: 'user-42', name: 'Helpful support assistant')
+client.banks.update(bank_id: 'user-42', mission: 'Support users clearly')
+client.banks.get('user-42')
+client.banks.stats('user-42')
+client.banks.delete('user-42')
+
+# chunk retrieval (client-level)
+client.chunks.get('chunk-1')
+
+# bank resources
+bank.stats
+bank.consolidate
+
+bank.memories.list(type: :world, q: 'diet', limit: 50, offset: 0)
+bank.memories.get('mem-1')
+bank.memories.delete(type: :experience)
+
+bank.mental_models.list(tags: ['team'], tags_match: :all)
+bank.mental_models.create(name: 'Team model', source_query: 'How does team communicate?')
+bank.mental_models.get('team-model')
+bank.mental_models.update(mental_model_id: 'team-model', max_tokens: 4096)
+bank.mental_models.refresh('team-model')
+bank.mental_models.delete('team-model')
+
+bank.directives.create(name: 'No competitors', content: 'Never recommend competitors.')
+bank.directives.list(tags: ['policy'], tags_match: :exact, active_only: true)
+bank.directives.get('dir-1')
+bank.directives.update(directive_id: 'dir-1', is_active: false)
+bank.directives.delete('dir-1')
+
+bank.documents.list(q: 'proposal', limit: 20, offset: 0)
+bank.documents.get('doc-1')
+bank.documents.delete('doc-1')
+
+bank.entities.list(limit: 20, offset: 0)
+bank.entities.get('ent-1')
+
+bank.operations.list(status: 'pending', limit: 20, offset: 0)
+bank.operations.get('op-123')
+bank.operations.wait(%w[op-123 op-456], interval: 0.5, timeout: 60, backoff: :exponential, max_interval: 30)
+bank.operations.cancel('op-123')
+
+bank.observations.delete
+bank.observations.delete_for_memory('mem-1')
+
+bank.tags.list(q: 'user:*', limit: 100, offset: 0)
+
+bank.config.get
+bank.config.patch(updates: { llm_model: 'gpt-4.1' })
+bank.config.reset
+
+bank.graph.get(type: 'world', q: 'alice', tags: ['team'], tags_match: 'all_strict', limit: 100)
+
+```
+
+## Error Handling
+
+All gem errors inherit from `Hindsight::Error`.
+
+- `Hindsight::ValidationError`
+- `Hindsight::ConnectionError`
+- `Hindsight::TimeoutError`
+- `Hindsight::APIError` (`status`, `body`, `retriable?`)
+- `Hindsight::FeatureNotSupported`
+
+`APIError#message` includes status context; use `e.body` for full server payload.
+
+Example:
+
+```ruby
+begin
+  bank.retain('hello')
+rescue Hindsight::APIError => e
+  warn "status=#{e.status} retriable=#{e.retriable?} body=#{e.body.inspect}"
+end
+```
+
+## Type Objects
+
+- `Hindsight::Types::Fact`
+- `Hindsight::Types::RecallResult`
+- `Hindsight::Types::Reflection`
+- `Hindsight::Types::OperationReceipt`
+- `Hindsight::Types::OperationStatus`
+
+Notes:
+
+- `Fact#type` is optional; when the API payload omits type, it is `nil`.
+- Type parsers normalize hash keys internally and read API fields using string-key conventions.
+
+## Compatibility Notes
+
+- Requires Ruby `>= 3.1`
+- Uses Faraday 2.x and `faraday-multipart`
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```

data/hindsight-ruby.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/hindsight/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "hindsight-ruby"
+  spec.version = Hindsight::VERSION
+  spec.authors = ["Andrey Samsonov"]
+
+  spec.summary = "Standalone Hindsight API client for Ruby"
+  spec.description = "Framework-agnostic ruby client for Hindsight APIs."
+  spec.homepage = "https://github.com/kryzhovnik/hindsight-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "lib/**/*",
+      "README.md",
+      "LICENSE.txt",
+      "hindsight-ruby.gemspec"
+    ]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+
+  spec.add_development_dependency "rake", ">= 13.0"
+  spec.add_development_dependency "rspec", ">= 3.13"
+  spec.add_development_dependency "webmock", ">= 3.0"
+end

data/lib/hindsight/bank.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'errors'
+require_relative 'option_validation'
+require_relative 'upload_normalizer'
+require_relative 'types/payload'
+require_relative 'types/operation_receipt'
+require_relative 'types/recall_result'
+require_relative 'types/reflection'
+
+module Hindsight
+  class Bank
+    attr_reader :client, :bank_id
+
+    def initialize(client:, bank_id:)
+      @client = client
+      @bank_id = OptionValidation.normalize_non_empty_string(bank_id, key: :bank_id)
+    end
+
+    def inspect
+      "#<#{self.class} bank_id=#{bank_id.inspect}>"
+    end
+
+    def retain(text, context: nil, tags: nil, document_id: nil, timestamp: nil,
+               metadata: nil, entities: nil, document_tags: nil, async: nil)
+      items = [
+        normalize_memory_item(
+          content: text, context: context, tags: tags,
+          document_id: document_id, timestamp: timestamp,
+          metadata: metadata, entities: entities
+        )
+      ]
+      submit_retain(items: items, document_tags: document_tags, async: async)
+    end
+
+    def retain_batch(items, document_tags: nil, async: nil)
+      raise ValidationError, 'items must be an Array' unless items.is_a?(Array)
+      raise ValidationError, 'items must not be empty' if items.empty?
+
+      submit_retain(
+        items: items.map.with_index { |item, index| normalize_batch_memory_item(item, index: index) },
+        document_tags: document_tags,
+        async: async
+      )
+    end
+
+    # Upload files for retention. Accepts file paths (String/Pathname) or upload
+    # hashes ({io:, filename:, content_type:}).
+    #
+    # SECURITY: When +files+ contains user-controlled paths, always set
+    # +allowed_paths+ to restrict which directories the gem may read from.
+    # Without it, any file readable by the process can be uploaded.
+    def retain_files(files, context: nil, tags: nil, metadata: nil, files_metadata: nil, allowed_paths: nil)
+      if client.file_upload_api_supported? == false
+        raise FeatureNotSupported, 'files/retain requires file_upload_api support'
+      end
+
+      uploads, closers = UploadNormalizer.normalize_uploads(files, allowed_paths: allowed_paths)
+      request = {
+        context: context,
+        tags: OptionValidation.normalize_tags(tags),
+        metadata: OptionValidation.normalize_hash(metadata, key: :metadata),
+        files_metadata: OptionValidation.normalize_files_metadata(files_metadata)
+      }.compact
+
+      body = client.request_multipart_files(
+        :post, "#{bank_path}/files/retain", uploads,
+        extra_fields: { request: JSON.generate(request) }
+      )
+      Types::OperationReceipt.from_api(body, bank: self)
+    ensure
+      Array(closers).each { |io| io.close unless io.closed? }
+    end
+
+    def recall(query, budget: :mid, max_tokens: 4096, types: nil, tags: nil, tags_match: nil,
+               query_timestamp: nil, include: nil, trace: nil)
+      payload = {
+        query: OptionValidation.normalize_query(query),
+        budget: OptionValidation.normalize_budget(budget).to_s,
+        max_tokens: OptionValidation.normalize_positive_integer(max_tokens, key: :max_tokens),
+        types: OptionValidation.normalize_fact_types(types),
+        tags: OptionValidation.normalize_tags(tags),
+        tags_match: OptionValidation.normalize_tags_match(tags_match)&.to_s,
+        query_timestamp: OptionValidation.normalize_optional_non_empty_string(query_timestamp, key: :query_timestamp),
+        include: OptionValidation.normalize_include_options(include, key: :include),
+        trace: OptionValidation.normalize_optional_boolean(trace, key: :trace)
+      }.compact
+
+      body = client.request_json(:post, "#{bank_path}/memories/recall", payload)
+      Types::RecallResult.from_api(body, query: payload[:query], budget: payload[:budget])
+    end
+
+    def reflect(query, budget: :mid, max_tokens: nil, include: nil, response_schema: nil, tags: nil, tags_match: nil)
+      payload = {
+        query: OptionValidation.normalize_query(query),
+        budget: OptionValidation.normalize_budget(budget).to_s,
+        max_tokens: max_tokens ? OptionValidation.normalize_positive_integer(max_tokens, key: :max_tokens) : nil,
+        include: OptionValidation.normalize_include_options(include, key: :include),
+        response_schema: OptionValidation.normalize_response_schema(response_schema),
+        tags: OptionValidation.normalize_tags(tags),
+        tags_match: OptionValidation.normalize_tags_match(tags_match)&.to_s
+      }.compact
+
+      body = client.request_json(:post, "#{bank_path}/reflect", payload)
+      Types::Reflection.from_api(body)
+    end
+
+    def stats
+      Types::Payload.stringify_keys(client.request_json(:get, "#{bank_path}/stats"))
+    end
+
+    def consolidate
+      Types::Payload.stringify_keys(client.request_json(:post, "#{bank_path}/consolidate"))
+    end
+
+    def memories
+      @memories ||= Resources::Memories.new(client: client, base_path: bank_path)
+    end
+
+    def mental_models
+      @mental_models ||= Resources::MentalModels.new(client: client, base_path: bank_path)
+    end
+
+    def directives
+      @directives ||= Resources::Directives.new(client: client, base_path: bank_path)
+    end
+
+    def documents
+      @documents ||= Resources::Documents.new(client: client, base_path: bank_path)
+    end
+
+    def entities
+      @entities ||= Resources::Entities.new(client: client, base_path: bank_path)
+    end
+
+    def operations
+      @operations ||= Resources::Operations.new(client: client, base_path: bank_path)
+    end
+
+    def observations
+      @observations ||= Resources::Observations.new(client: client, base_path: bank_path)
+    end
+
+    def tags
+      @tags ||= Resources::Tags.new(client: client, base_path: bank_path)
+    end
+
+    def config
+      @config ||= Resources::Config.new(client: client, base_path: bank_path)
+    end
+
+    def graph
+      @graph ||= Resources::Graph.new(client: client, base_path: bank_path)
+    end
+
+    private
+
+    def bank_path
+      @bank_path ||= "/v1/default/banks/#{client.escape(bank_id)}"
+    end
+
+    def submit_retain(items:, document_tags:, async:)
+      async_value = OptionValidation.normalize_optional_boolean(async, key: :async)
+      payload = {
+        async: async_value,
+        document_tags: OptionValidation.normalize_tags(document_tags),
+        items: items
+      }
+      body = client.retain_json(bank_path, payload.compact)
+      async_value ? Types::OperationReceipt.from_api(body, bank: self) : body
+    end
+
+    def normalize_memory_item(content:, context: nil, tags: nil, document_id: nil,
+                              timestamp: nil, metadata: nil, entities: nil)
+      {
+        content: OptionValidation.normalize_query(content, key: :content),
+        context: context,
+        tags: OptionValidation.normalize_tags(tags),
+        document_id: document_id,
+        timestamp: OptionValidation.normalize_optional_non_empty_string(timestamp, key: :timestamp),
+        metadata: OptionValidation.normalize_hash(metadata, key: :metadata),
+        entities: OptionValidation.normalize_entities(entities)
+      }.compact
+    end
+
+    def normalize_batch_memory_item(item, index:)
+      raise ValidationError, "items[#{index}] must be a Hash" unless item.is_a?(Hash)
+
+      value = Types::Payload.stringify_keys(item)
+      raise ValidationError, "items[#{index}] must include :content" unless value.key?('content')
+
+      normalize_memory_item(
+        content: value['content'],
+        context: value['context'],
+        tags: value['tags'],
+        document_id: value['document_id'],
+        timestamp: value['timestamp'],
+        metadata: value['metadata'],
+        entities: value['entities']
+      )
+    end
+  end
+end