robot_lab-document_store 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 421276837702fa51fef2d7eb2e776634f7f5e9f937b85bc832afb1ba6d0da978
-  data.tar.gz: 6ecb47f66596a40a8e36abe49880f0001b1bc6ed6b9f3fd976b4c0b36b6ede29
+  metadata.gz: c76daa301371b72ad1a128cc287b84a4b86962851d581807a3b4a86eea758d7a
+  data.tar.gz: 3dd0e51ac30391feb45ea59cede650a1d137b9fc54d02cbf63479a484036c6aa
 SHA512:
-  metadata.gz: 6f56c72155401b3f79acbd3ed9c70ab8a62081b2a7b587d415a93a5143bc716f73a54c2eecaf785598ef923b271dfb7dad3e799cf7c8c06dbbb0b5a311b79a29
-  data.tar.gz: 2643e466fefa4f97c2ce218e33e2904c3d40845b242276997e58475f46b59517e05cf810e5c43aab80e978b1b43990fe9c990990147e927a0776fb93c3c6fda9
+  metadata.gz: fb965431ab53192605471ec0b06f9664fc57bea6a97e53bd0956b074e53e95f34a4c689624a171bb655847cbb8d45b9417f6112daa2e89de23618cb2978f94fd
+  data.tar.gz: ee8900ebb335b40ffc7adc00db2562919a3d7fbb5eec492cda848b041a458154ca513ac1a8f0a3c8c9a665836d7739faa67e102710576d89d49c8f502115a3a0

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-document_store — vector embeddings & semantic search.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-document_store".freeze
+
+  header "robot_lab-document_store v#{gem_version} — vector embeddings & semantic search"
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1 @@
+9	lib/robot_lab/document_store.rb

data/.rubocop.yml

@@ -1,173 +1 @@
-AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  TargetRubyVersion: 4.0
-  Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-    - 'dead_code/**/*'
-
-# ── Style: disabled cops ───────────────────────────────────────────────────
-Style/StringLiterals:
-  Enabled: false
-
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Ruby 4.0 freezes string literals by default
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
-
-Style/MultilineTernaryOperator:
-  Enabled: false
-
-Style/SafeNavigation:
-  Enabled: false
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/RescueStandardError:
-  Enabled: false
-
-Style/OneClassPerFile:
-  Enabled: false
-
-# Both % and format/sprintf are acceptable
-Style/FormatString:
-  Enabled: false
-
-# String concatenation and interpolation are both acceptable
-Style/StringConcatenation:
-  Enabled: false
-
-# ── Layout ─────────────────────────────────────────────────────────────────
-Layout/LineLength:
-  Max: 140
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-# ── Naming ─────────────────────────────────────────────────────────────────
-# Single-char params (c, e, n) are acceptable throughout
-Naming/MethodParameterName:
-  Enabled: false
-
-Naming/VariableNumber:
-  Exclude:
-    - 'test/**/*'
-
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-
-# set_results and similar explicit setters are clear and conventional
-Naming/AccessorMethodName:
-  Enabled: false
-
-
-# has_tool_calls? and similar are clear and conventional
-Naming/PredicatePrefix:
-  Enabled: false
-
-# Test helper methods don't need to follow predicate naming rules
-Naming/PredicateMethod:
-  Exclude:
-    - 'test/**/*'
-
-# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
-# Library and framework methods commonly accept args for API/documentation purposes
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-
-Lint/EmptyBlock:
-  Exclude:
-    - 'test/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'Rakefile'
-    - 'test/**/*'
-
-# ── Gemspec ────────────────────────────────────────────────────────────────
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: Gemfile
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
-
-# ── Metrics ────────────────────────────────────────────────────────────────
-# Framework-level code (routers, parsers, orchestrators) is inherently complex.
-# Flog is the primary complexity gate — these RuboCop thresholds catch only
-# egregious outliers without false-positiving every dispatch method.
-
-Metrics/MethodLength:
-  Max: 35
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-  Exclude:
-    - 'test/**/*'
-
-Metrics/AbcSize:
-  Max: 40
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ClassLength:
-  Max: 600
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ModuleLength:
-  Max: 200
-  Exclude:
-    - 'test/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-# Long method signatures with keyword args are a Ruby framework idiom
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
-    - 'test/**/*'
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
 ## [0.2.1] - 2026-05-19
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-document_store` provides a thread-safe, in-memory semantic document store for RobotLab. Documents are embedded and retrieved by cosine similarity. It uses `fastembed` (BAAI/bge-small-en-v1.5) when available, and falls back to a lightweight TF-IDF word-frequency embedder when fastembed is not installed.
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite
+ruby -Ilib:test test/<file>  # Run a single test file
+```
+
+## Architecture
+
+The gem is a single class: `RobotLab::DocumentStore` (`lib/robot_lab/document_store.rb`).
+
+### Key Methods
+
+```ruby
+store = RobotLab::DocumentStore.new                  # fastembed model chosen automatically
+store = RobotLab::DocumentStore.new(model_name: "...") # override fastembed model
+
+store.store(:key, "text")           # embed and store; replaces existing key
+store.search("query", limit: 5)     # returns Array<{key:, text:, score:}>
+store.size                          # Integer
+store.keys                          # Array<Symbol>
+store.empty?                        # Boolean
+store.delete(:key)                  # remove one document
+store.clear                         # remove all documents
+```
+
+Search results are sorted by score descending (0.0–1.0). The fastembed model is initialised lazily on the first `store` or `search` call — the ONNX model file is downloaded then cached locally.
+
+### Embedding Paths
+
+**Fastembed path** (when `fastembed` gem is installed):
+- `passage_embed` for stored documents, `query_embed` for search queries — asymmetric embedding per the BGE model's design
+- Dense float vectors, cosine similarity computed inline
+
+**Fallback TF-IDF path** (when fastembed is absent):
+- Stop-word filtered, Porter-style stemmed word frequency vectors
+- Sparse `Hash{String => Float}` L2-normalised vectors
+- `sparse_cosine` for similarity — no semantic understanding, lexical overlap only
+- Good for development and testing without downloading ONNX models
+
+### Thread Safety
+
+All reads and writes to `@documents` are protected by a `Mutex`. The fastembed model is not Mutex-protected because `Fastembed::TextEmbedding` is itself thread-safe.
+
+### Integration with robot_lab Memory
+
+When `robot_lab-document_store` is loaded alongside `robot_lab`, the Memory class gains:
+```ruby
+memory.store_document(:key, text)
+memory.search_documents("query", limit: 5)
+```
+
+## Key Constraints
+
+- Documents are stored entirely in memory — the store does not persist across process restarts.
+- Keys are coerced to `Symbol`. Storing under the same key replaces the previous document.
+- The TF-IDF fallback has no semantic understanding — "car" and "automobile" will not match. Use fastembed for production.
+- `FASTEMBED_AVAILABLE` is set at load time and cannot be changed at runtime.
+
+## Testing
+
+- Minitest with SimpleCov (`minimum_coverage line: 95, branch: 75` enforced)
+- Tests stub fastembed to avoid downloading the ONNX model — do not call the real fastembed model in unit tests
+- Coverage: 98.89% line / 95.83% branch

data/Rakefile

@@ -24,16 +24,6 @@ task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
 
-desc 'Check code style with RuboCop'
-task :rubocop do
-  sh 'bundle exec rubocop'
-end
-
-desc 'Auto-correct RuboCop offenses'
-task :rubocop_fix do
-  sh 'bundle exec rubocop -a'
-end
-
 desc 'Check code complexity with Flog (warn >=20, fail >=50)'
 task :flog_check do
   require 'flog'
@@ -71,36 +61,62 @@ task :flog_check do
   end
 end
 
-desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
-task :quality do
-  results = {}
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Tests + Coverage'
-  puts '=' * 60
-  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+  mass_threshold = 50
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: RuboCop'
-  puts '=' * 60
-  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Flog Complexity'
-  puts '=' * 60
-  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
 
   puts "\n#{'=' * 60}"
-  puts 'Quality Summary'
+  puts 'Quality Gate Summary'
   puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
   end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
   puts '=' * 60
 
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
 end
 
 namespace :docs do

data/docs/getting_started.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- Ruby 3.1+
+- Ruby 3.2+
 - **fastembed** (recommended) — requires a platform that can run ONNX Runtime (x86_64 and ARM64 macOS/Linux). On first use the ~23 MB `BAAI/bge-small-en-v1.5` model file is downloaded and cached in `~/.cache/fastembed`.
 - Without fastembed the store still works using the built-in TF-IDF fallback (see [Fallback Mode](#fallback-mode) below).
 

data/docs/how_it_works.md

@@ -64,7 +64,7 @@ term frequencies.
 raw text
   → downcase
   → tokenise /[a-z]+/   (ASCII only — Unicode letters are dropped)
-  → remove STOP_WORDS   (38 common English words: a, an, the, is, are, …)
+  → remove STOP_WORDS   (45 common English words: a, an, the, is, are, …)
   → Porter-style stem   (strips: -ies, -ness, -ment, -tion, -ing, -ed, -er, -ly, -s)
   → count term frequencies
   → L2-normalise counts  (divide each count by the Euclidean norm of the count vector)

data/lib/robot_lab/document_store/version.rb

@@ -2,6 +2,6 @@
 
 module RobotLab
   class DocumentStore
-    VERSION = '0.2.1'
+    VERSION = '0.2.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-document_store
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -50,8 +50,11 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -93,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Embedding-based semantic document store for RobotLab agents
 test_files: []