robot_lab-document_store 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe6aeaf2a0fd6a0c1dd5b827a9382e3804cf9cf6e8573fdd9c75063fccd87a36
-  data.tar.gz: 350a44adfb40048c467166a1bfc37dd169941a35c4f5e3dd56ace185e39ba27b
+  metadata.gz: 5add23edc59a87fac16aaab24cc061392c241b6d0e0065aa36832dc5681342d6
+  data.tar.gz: 9fb1b9c37b3dcdee87ede9c3e0ce43e6013b6964d1268c39c9cb83a1c0a389ff
 SHA512:
-  metadata.gz: 05bc51a7b278d57d7bf8b1bb8535d5520ac41093112b0080c0f2f6e7eb554101d212b8c3065564f25a031ce3439f7b8ad9562fa93a9ef9a4091d78f3d20bdea2
-  data.tar.gz: 62694a390bbcd9a2492466eef6102fd821ae670ca30b694283d25f73f4fa7c504e9c62e2e32509ebc2f3f7700d63499e74153111bd781bf190ea39c76f714137
+  metadata.gz: 3834e2af8b84030daa4b8641f1e86697dbb9d88d37e9ddc975f81a40df3d6b632e48a0459da012466dc2a695b1e9857ea7fbdb0f5524724578e9754b3b6556bc
+  data.tar.gz: c9d07c4c8b6d0f5bffc7c1e7a27c7d5c434a4ad85e6ed2336b6e751bd6e23c6a5ef1c6612c2650947a90928aa30561e0b6e5725ebb5bb2ed8611a23123633ff1

data/.rubocop.yml

@@ -0,0 +1,173 @@
+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/**/*'

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+### Fixed
+- Model name in README and docs corrected to `BAAI/bge-small-en-v1.5` (was incorrectly listed as `bge-base`)
+- `register_extension` call guarded with `defined?(RobotLab) && RobotLab.respond_to?(:register_extension)` so the file loads safely without robot_lab core
+- Instance variable `@fastembed_model` renamed from `@model` to eliminate shadowing risk
+- `FASTEMBED_AVAILABLE` constant moved into `DocumentStore` class (was at module level)
+- `STOP_WORDS` constant moved before `private` keyword (was defined after it)
+- `sparse_cosine` parameter names corrected to `vec_a`/`vec_b`; uses `each_value` for the second vector
+
+### Added
+- Full test suite covering fastembed path, TF-IDF fallback path, and cosine edge cases (27 tests, 44 assertions)
+- SimpleCov branch coverage with thresholds (line: 95%, branch: 75%)
+- `quality` Rake task: runs tests + coverage, RuboCop, and Flog in sequence
+- Complete RBS type signatures in `sig/robot_lab/document_store.rbs`
+- Example script `examples/01_basic_usage.rb` with companion Markdown documents
+
+### Changed
+- Development dependencies moved from gemspec to Gemfile (per `Gemspec/DevelopmentDependencies` cop)
+- Example renamed from `26_document_store.rb` to `01_basic_usage.rb`
+
 ## [0.1.0] - 2026-05-07
 
 - Initial release

data/README.md

@@ -49,7 +49,7 @@ store = RobotLab::DocumentStore.new(
 )
 ```
 
-The default model is `"BAAI/bge-base-en-v1.5"`.
+The default model is `"BAAI/bge-small-en-v1.5"`.
 
 ## Using with RobotLab Robots
 

data/Rakefile

@@ -1,8 +1,116 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
 
 task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+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'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
+task :quality do
+  results = {}
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Tests + Coverage'
+  puts '=' * 60
+  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: RuboCop'
+  puts '=' * 60
+  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Flog Complexity'
+  puts '=' * 60
+  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Summary'
+  puts '=' * 60
+  results.each do |gate, status|
+    icon = status == :pass ? 'PASS' : 'FAIL'
+    puts "  [#{icon}] #{gate}"
+  end
+  puts '=' * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
+end
+
+namespace :docs do
+  desc 'Build MkDocs documentation'
+  task :build do
+    sh 'mkdocs build'
+  end
+
+  desc 'Serve MkDocs documentation locally on http://localhost:8000'
+  task :serve do
+    sh 'mkdocs serve'
+  end
+end

data/docs/api_reference.md

@@ -0,0 +1,186 @@
+# API Reference
+
+All public methods of `RobotLab::DocumentStore`.
+
+## Constructor
+
+### `new(model_name: DEFAULT_MODEL)`
+
+Creates a new, empty document store.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_name` | `String` | `"BAAI/bge-small-en-v1.5"` | fastembed model name. Ignored when fastembed is unavailable. |
+
+```ruby
+# Default model
+store = RobotLab::DocumentStore.new
+
+# Custom model
+store = RobotLab::DocumentStore.new(model_name: "BAAI/bge-base-en-v1.5")
+```
+
+The embedding model is initialised lazily — no download or computation happens
+at construction time.
+
+---
+
+## Writing Documents
+
+### `store(key, text) → self`
+
+Embeds `text` and stores it under `key`. If a document already exists under that
+key it is replaced. Embedding happens synchronously before the method returns.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `Symbol` \| `String` | Identifier for the document. Strings are converted to `Symbol` internally. |
+| `text` | `String` | The document text to embed and store. |
+
+**Returns:** `self` — supports method chaining.
+
+```ruby
+store.store(:readme,   File.read("README.md"))
+     .store(:changelog, File.read("CHANGELOG.md"))
+     .store(:guide,     File.read("GUIDE.md"))
+```
+
+---
+
+## Searching
+
+### `search(query, limit: 5) → Array<Hash>`
+
+Embeds `query` and returns the `limit` most similar documents ranked by cosine
+similarity score descending.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `String` | — | Natural-language search query. |
+| `limit` | `Integer` | `5` | Maximum number of results to return. |
+
+**Returns:** `Array` of result hashes, each containing:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `:key` | `Symbol` | The document key |
+| `:text` | `String` | The stored document text |
+| `:score` | `Float` | Cosine similarity score, range `0.0..1.0` |
+
+Results are sorted by `:score` descending (most similar first). Returns `[]` if
+the store is empty.
+
+```ruby
+results = store.search("database connection pool exhausted", limit: 3)
+
+results.each do |r|
+  puts "#{r[:key].to_s.ljust(24)} score=#{r[:score].round(3)}"
+  puts "  #{r[:text][0, 80]}…"
+end
+```
+
+!!! tip "Score interpretation"
+    Scores above `0.7` indicate strong semantic similarity. Scores below `0.3`
+    typically indicate weak or no relationship. The exact thresholds depend on
+    the model and your document corpus.
+
+---
+
+## Reading Metadata
+
+### `size → Integer`
+
+Returns the number of stored documents.
+
+```ruby
+store.size  # => 0
+store.store(:a, "text")
+store.size  # => 1
+```
+
+### `keys → Array<Symbol>`
+
+Returns the keys of all stored documents in insertion order.
+
+```ruby
+store.store(:alpha, "…")
+store.store(:beta,  "…")
+store.keys  # => [:alpha, :beta]
+```
+
+### `empty? → Boolean`
+
+Returns `true` if no documents are stored.
+
+```ruby
+store.empty?  # => true
+store.store(:a, "text")
+store.empty?  # => false
+```
+
+---
+
+## Removing Documents
+
+### `delete(key) → self`
+
+Removes the document stored under `key`. No-op if the key does not exist.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `Symbol` \| `String` | Key to remove. |
+
+**Returns:** `self`.
+
+```ruby
+store.delete(:outdated_doc)
+store.delete("also_works_with_strings")
+```
+
+### `clear → self`
+
+Removes all stored documents.
+
+**Returns:** `self`.
+
+```ruby
+store.clear
+store.empty?  # => true
+```
+
+---
+
+## Constants
+
+### `DEFAULT_MODEL`
+
+```ruby
+RobotLab::DocumentStore::DEFAULT_MODEL  # => "BAAI/bge-small-en-v1.5"
+```
+
+The fastembed model used when no `model_name:` is specified.
+
+### `STOP_WORDS`
+
+A frozen `Set<String>` of common English words excluded from TF-IDF indexing
+(`a`, `an`, `the`, `is`, `are`, …). Only relevant when fastembed is unavailable.
+
+---
+
+## Thread Safety
+
+All public methods are thread-safe. An internal `Mutex` serialises access to
+the document hash. You can safely share a single `DocumentStore` instance across
+Puma threads, Sidekiq workers, or Ractor-based agents.
+
+```ruby
+# Safe: multiple threads can store and search concurrently
+store = RobotLab::DocumentStore.new
+
+threads = 10.times.map do |i|
+  Thread.new { store.store(:"doc_#{i}", "Document #{i} text content") }
+end
+threads.each(&:join)
+
+store.size  # => 10
+```

data/docs/assets/architecture.svg

@@ -0,0 +1,140 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 540" font-family="Roboto Mono, monospace">
+  <!-- transparent background -->
+
+  <!-- ── Title ── -->
+  <text x="410" y="32" text-anchor="middle" font-size="16" font-weight="bold" fill="#e2e8f0">DocumentStore — Embedding Pipeline</text>
+
+  <!-- ══════════════════════════════════════════════════════
+       LEFT COLUMN — STORE PATH
+  ═══════════════════════════════════════════════════════ -->
+
+  <!-- store() label -->
+  <text x="160" y="72" text-anchor="middle" font-size="13" font-weight="bold" fill="#94a3b8">store(key, text)</text>
+
+  <!-- Input text box -->
+  <rect x="60" y="82" width="200" height="44" rx="6" fill="#1e293b" stroke="#475569" stroke-width="1.5"/>
+  <text x="160" y="100" text-anchor="middle" font-size="11" fill="#94a3b8">Document Text</text>
+  <text x="160" y="116" text-anchor="middle" font-size="10" fill="#64748b">"Postgres query slow…"</text>
+
+  <!-- arrow down -->
+  <line x1="160" y1="126" x2="160" y2="150" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- fastembed decision diamond -->
+  <polygon points="160,152 210,176 160,200 110,176" fill="#1e3a5f" stroke="#3b82f6" stroke-width="1.5"/>
+  <text x="160" y="172" text-anchor="middle" font-size="10" fill="#93c5fd">fastembed</text>
+  <text x="160" y="185" text-anchor="middle" font-size="10" fill="#93c5fd">available?</text>
+
+  <!-- YES branch → passage_embed -->
+  <line x1="210" y1="176" x2="270" y2="176" stroke="#22c55e" stroke-width="1.5" marker-end="url(#arrGreen)"/>
+  <text x="237" y="169" text-anchor="middle" font-size="9" fill="#22c55e">yes</text>
+
+  <rect x="270" y="158" width="130" height="36" rx="6" fill="#14532d" stroke="#22c55e" stroke-width="1.5"/>
+  <text x="335" y="173" text-anchor="middle" font-size="10" fill="#86efac">passage_embed()</text>
+  <text x="335" y="187" text-anchor="middle" font-size="9" fill="#4ade80">dense Float[]  (384d)</text>
+
+  <!-- NO branch → fallback_vector -->
+  <line x1="160" y1="200" x2="160" y2="224" stroke="#f59e0b" stroke-width="1.5" marker-end="url(#arrAmber)"/>
+  <text x="172" y="216" font-size="9" fill="#f59e0b">no</text>
+
+  <rect x="60" y="224" width="200" height="36" rx="6" fill="#451a03" stroke="#f59e0b" stroke-width="1.5"/>
+  <text x="160" y="239" text-anchor="middle" font-size="10" fill="#fcd34d">fallback_vector()</text>
+  <text x="160" y="253" text-anchor="middle" font-size="9" fill="#fbbf24">sparse Hash  TF-IDF L2</text>
+
+  <!-- merge to store -->
+  <line x1="335" y1="194" x2="335" y2="310" stroke="#22c55e" stroke-width="1.2" stroke-dasharray="4,3"/>
+  <line x1="160" y1="260" x2="160" y2="310" stroke="#f59e0b" stroke-width="1.2" stroke-dasharray="4,3"/>
+  <line x1="160" y1="310" x2="248" y2="310" stroke="#475569" stroke-width="1.2"/>
+  <line x1="335" y1="310" x2="248" y2="310" stroke="#475569" stroke-width="1.2"/>
+  <line x1="248" y1="310" x2="248" y2="326" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- @documents store -->
+  <rect x="148" y="326" width="200" height="44" rx="6" fill="#1e1b4b" stroke="#818cf8" stroke-width="1.5"/>
+  <text x="248" y="344" text-anchor="middle" font-size="11" fill="#a5b4fc">@documents</text>
+  <text x="248" y="360" text-anchor="middle" font-size="9" fill="#6366f1">{ key → { text, vector } }</text>
+
+  <!-- Mutex badge -->
+  <rect x="334" y="330" width="50" height="18" rx="4" fill="#312e81" stroke="#6366f1" stroke-width="1"/>
+  <text x="359" y="343" text-anchor="middle" font-size="9" fill="#c7d2fe">Mutex</text>
+
+  <!-- ══════════════════════════════════════════════════════
+       RIGHT COLUMN — SEARCH PATH
+  ═══════════════════════════════════════════════════════ -->
+
+  <!-- search() label -->
+  <text x="640" y="72" text-anchor="middle" font-size="13" font-weight="bold" fill="#94a3b8">search(query, limit:)</text>
+
+  <!-- Query text box -->
+  <rect x="540" y="82" width="200" height="44" rx="6" fill="#1e293b" stroke="#475569" stroke-width="1.5"/>
+  <text x="640" y="100" text-anchor="middle" font-size="11" fill="#94a3b8">Query String</text>
+  <text x="640" y="116" text-anchor="middle" font-size="10" fill="#64748b">"Why is my query slow?"</text>
+
+  <!-- arrow down -->
+  <line x1="640" y1="126" x2="640" y2="150" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- decision diamond -->
+  <polygon points="640,152 690,176 640,200 590,176" fill="#1e3a5f" stroke="#3b82f6" stroke-width="1.5"/>
+  <text x="640" y="172" text-anchor="middle" font-size="10" fill="#93c5fd">fastembed</text>
+  <text x="640" y="185" text-anchor="middle" font-size="10" fill="#93c5fd">available?</text>
+
+  <!-- YES → query_embed -->
+  <line x1="690" y1="176" x2="750" y2="176" stroke="#22c55e" stroke-width="1.5" marker-end="url(#arrGreen)"/>
+  <text x="717" y="169" text-anchor="middle" font-size="9" fill="#22c55e">yes</text>
+
+  <rect x="750" y="158" width="56" height="36" rx="6" fill="#14532d" stroke="#22c55e" stroke-width="1.5"/>
+  <text x="778" y="173" text-anchor="middle" font-size="10" fill="#86efac">query_</text>
+  <text x="778" y="187" text-anchor="middle" font-size="10" fill="#86efac">embed()</text>
+
+  <!-- NO → fallback_vector -->
+  <line x1="640" y1="200" x2="640" y2="224" stroke="#f59e0b" stroke-width="1.5" marker-end="url(#arrAmber)"/>
+  <text x="652" y="216" font-size="9" fill="#f59e0b">no</text>
+
+  <rect x="540" y="224" width="200" height="36" rx="6" fill="#451a03" stroke="#f59e0b" stroke-width="1.5"/>
+  <text x="640" y="239" text-anchor="middle" font-size="10" fill="#fcd34d">fallback_vector()</text>
+  <text x="640" y="253" text-anchor="middle" font-size="9" fill="#fbbf24">sparse Hash  TF-IDF L2</text>
+
+  <!-- query_vec arrow to cosine_similarity -->
+  <line x1="640" y1="260" x2="640" y2="326" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="778" y1="194" x2="778" y2="310" stroke="#22c55e" stroke-width="1.2" stroke-dasharray="4,3"/>
+  <line x1="778" y1="310" x2="700" y2="310" stroke="#475569" stroke-width="1.2"/>
+  <line x1="700" y1="310" x2="700" y2="326" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- cosine_similarity box -->
+  <rect x="530" y="326" width="240" height="44" rx="6" fill="#1c1917" stroke="#d97706" stroke-width="1.5"/>
+  <text x="650" y="344" text-anchor="middle" font-size="11" fill="#fbbf24">cosine_similarity()</text>
+  <text x="650" y="360" text-anchor="middle" font-size="9" fill="#92400e">dot(q,p) / (‖q‖ · ‖p‖)  → score 0..1</text>
+
+  <!-- @documents feeds cosine via arrow -->
+  <line x1="348" y1="348" x2="530" y2="348" stroke="#818cf8" stroke-width="1.5" marker-end="url(#arrPurple)"/>
+  <text x="435" y="341" text-anchor="middle" font-size="9" fill="#818cf8">stored vectors</text>
+
+  <!-- Results box -->
+  <rect x="530" y="412" width="240" height="44" rx="6" fill="#1e293b" stroke="#38bdf8" stroke-width="1.5"/>
+  <text x="650" y="430" text-anchor="middle" font-size="11" fill="#7dd3fc">Ranked Results</text>
+  <text x="650" y="446" text-anchor="middle" font-size="9" fill="#38bdf8">[{ key:, text:, score: }, …]  sorted desc</text>
+
+  <line x1="650" y1="370" x2="650" y2="412" stroke="#475569" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- ══════════════════════════════════════════════════════
+       BOTTOM — FALLBACK DETAIL
+  ═══════════════════════════════════════════════════════ -->
+
+  <text x="410" y="490" text-anchor="middle" font-size="11" fill="#64748b">
+    TF-IDF fallback:  tokenise → strip stop words → Porter stem → L2-normalise → sparse cosine dot product
+  </text>
+
+  <!-- ── arrowhead markers ── -->
+  <defs>
+    <marker id="arr" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L8,3 z" fill="#475569"/>
+    </marker>
+    <marker id="arrGreen" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L8,3 z" fill="#22c55e"/>
+    </marker>
+    <marker id="arrAmber" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L8,3 z" fill="#f59e0b"/>
+    </marker>
+    <marker id="arrPurple" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L8,3 z" fill="#818cf8"/>
+    </marker>
+  </defs>
+</svg>