pikuri-vectordb 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a64900380a7c48712b1ea58053f141d1c6f5da57e723925ca24319899e91607
+  data.tar.gz: 5ed708f037e0cd979e1a2018b9fabf0d996679befbcca69def2d58ce8aac8fd4
+SHA512:
+  metadata.gz: ada1509afe42590bae569b032cc88fe4ae2ed724a152388fc710b3fe5275f256fee2af6e2db29bb82469d11d651698a653addf10a7679df4b57acadaaab76720
+  data.tar.gz: d25268e97f43a4c73fb4eea1e957a3c9129b4d543e3c78e767318cc784eb0898ec3ba647210b6d969521a2214c6934c5f2aadb387e32f98ca655ff5eee0bb92c

data/README.md

@@ -0,0 +1,121 @@
+# pikuri-vectordb
+
+Local-corpus vector search + agentic RAG for the
+[pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant toolkit.
+
+> **Status:** skeleton — gem scaffolding only. The
+> `Pikuri::VectorDb::Extension` and `vectordb_search` tool are
+> being built in subsequent commits. See `IDEAS.md` §"Vector DB /
+> RAG" for the design.
+
+Will provide:
+
+- `Pikuri::VectorDb::Extension` — wires a `vectordb_search` tool +
+  a `vectordb_reindex` tool onto a `Pikuri::Agent` via
+  `c.add_extension(...)` inside the `Agent.new` block.
+- `Pikuri::VectorDb::Backend::InMemory` — pure-Ruby cosine over
+  `Array<Float>`. The educational default; reads in ~40 lines.
+  RAM-only; everything reloads from sources on every boot.
+- `Pikuri::VectorDb::Backend::Chroma` — thin Faraday HTTP client
+  against a self-hosted ChromaDB. The persistent option.
+- `Pikuri::VectorDb::Embedder` — thin wrapper over `RubyLLM.embed`
+  so tests can inject a fake without monkey-patching ruby_llm.
+- `Pikuri::VectorDb::Reranker::LlamaServer` — optional quality
+  knob. Speaks `/v1/rerank` against a cross-encoder model on a
+  llama.cpp server. Passing `reranker: nil` to the extension
+  skips reranking; retrieval falls back to vector-only top-k.
+- `Pikuri::VectorDb::Chunker::FixedWindow` + `Tokenizer::*` —
+  the chunking pipeline. Tokenizer is a duck-typed protocol
+  (`count(text) -> Integer`) with two impls in v1:
+  `Tokenizer::CharHeuristic` (default, ~4 chars/token rule) and
+  `Tokenizer::LlamaServer` (POST `/tokenize` against the
+  embedder's endpoint).
+- Text extraction reuses `Pikuri::FileType.read_as_text` from
+  pikuri-core — plain text / Markdown / PDF. HTML extraction
+  is a deferred follow-up; v1 corpora skew toward Markdown
+  notes and PDF docs in practice.
+- `Pikuri::VectorDb::LIBRARIAN` — bundled
+  `Pikuri::SubAgent::Persona` constant. Hosts wire it via
+  `SubAgent::Extension.new(personas: [..., LIBRARIAN])` — same
+  shape `pikuri-code` uses for `GIT_REPO_RESEARCHER`.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'pikuri-vectordb'
+```
+
+## Usage (preview — not yet wired)
+
+```ruby
+require 'pikuri-core'
+require 'pikuri-vectordb'
+
+backend = Pikuri::VectorDb::Backend::InMemory.new
+# Or for persistent storage:
+#   backend = Pikuri::VectorDb::Backend::Chroma.new(
+#     host: 'localhost', port: 8000, collection: 'my-docs',
+#   )
+agent = Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
+  c.add_extension(
+    Pikuri::VectorDb::Extension.new(
+      backend: backend,
+      source: '~/notes',
+    )
+  )
+end
+```
+
+Collection naming is Chroma-specific so it lives on
+`Backend::Chroma.new(collection:)`, not on the Extension —
+`Backend::InMemory` has no collection concept.
+
+For hosts that want recall behind a privilege-separated sub-agent
+(the trifecta-defense pattern — see `SECURITY.md` and `IDEAS.md`
+§"Vector DB / RAG"), additionally wire the `LIBRARIAN` persona
+via `pikuri-subagents`:
+
+```ruby
+require 'pikuri-subagents'
+
+c.add_extension(
+  Pikuri::SubAgent::Extension.new(
+    personas: [Pikuri::VectorDb::LIBRARIAN]
+  )
+)
+```
+
+## Three model endpoints
+
+A full assistant setup wants three LLM endpoints: chat (via
+`ruby_llm`), an embedder (via `RubyLLM.embed`), and an optional
+reranker (HTTP `/v1/rerank`). Recommended setup: **one
+`llama-server` running in router mode** — started with no
+`--model` flag, it serves every GGUF in `~/.cache/llama.cpp/`
+from a single port and loads whichever model each request asks
+for. Requires a recent enough `llama.cpp` build to include the
+[model-management feature](https://huggingface.co/blog/ggml-org/model-management-in-llamacpp);
+Ubuntu 26.04+ packages one. The guide's
+[chapter 1](../docs/guide/01-chat.md) walks through the setup;
+[chapter 3](../docs/guide/03-vectordb.md) adds the embedder and
+reranker on top.
+
+If you'd rather pin the reranker in its own process — to avoid
+paying the router's unload/reload cost on rerank requests —
+`Reranker::LlamaServer` takes its own `endpoint:` argument and
+can point at a separate `llama-server`. Otherwise pikuri stays
+agnostic: it just needs URLs.
+
+Larger multi-model runtimes (Ollama, LM Studio, ...) expose
+OpenAI-compatible endpoints and would also work, but pikuri's
+"small enough to audit" ethos keeps the recommended path on
+`llama.cpp` alone.
+
+## Further reading
+
+- **Design notes:** `IDEAS.md` §"Vector DB / RAG" at the repo
+  root.
+- **API reference:** browse the YARD docs at
+  <https://rubydoc.info/gems/pikuri-vectordb> (once published),
+  or run `bundle exec yard` in this directory for a local copy.

data/lib/pikuri/vector_db/backend/chroma.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Pikuri
+  module VectorDb
+    module Backend
+      # Thin Faraday HTTP client against a self-hosted Chroma
+      # server (v2 API). The persistent backend, behind the same
+      # duck-typed {Backend} protocol as {InMemory}: same method
+      # names, same return shapes, same +ArgumentError+ contract
+      # on empty input + non-positive +top_k+. Where the two
+      # diverge is the vector-dim contract — see below.
+      #
+      # == Two ways to get one
+      #
+      # * **Bring your own.** +Backend::Chroma.new(host:, port:,
+      #   collection:)+ against an existing chroma deployment
+      #   (production cluster, docker-compose stack, a chroma
+      #   already running on the host for an unrelated project).
+      #   The host owns the process; this class is purely the
+      #   HTTP client.
+      # * **Let pikuri manage it.** {ChromaServer.ensure_running}
+      #   spawns and supervises a chroma container under the
+      #   +pikuri-internal-chroma+ name, against a pinned image,
+      #   with a bind-mounted volume in the user's cache dir.
+      #   Its +#client(collection:)+ returns a +Backend::Chroma+
+      #   pre-pointed at the supervised container. The split is
+      #   deliberate: docker lifecycle and HTTP wire protocol
+      #   have nothing in common, so each lives in its own class.
+      #
+      # == Chroma v2 API
+      #
+      # Endpoints used:
+      #
+      # * +POST /api/v2/tenants/{tenant}/databases/{db}/collections+
+      #   with +get_or_create: true+ — idempotent collection
+      #   creation. Returns +{id, name, ...}+.
+      # * +POST /api/v2/.../collections/{id}/upsert+ — insert or
+      #   replace by id. Body carries parallel arrays of +ids+,
+      #   +embeddings+, +documents+, +metadatas+.
+      # * +POST /api/v2/.../collections/{id}/query+ — k-NN
+      #   search. Body: +{query_embeddings, n_results, include}+.
+      # * +GET /api/v2/.../collections/{id}/count+ — integer
+      #   count.
+      # * +DELETE /api/v2/.../collections/{id}+ — drop the
+      #   collection (used by +#delete_all+).
+      #
+      # == BYO embeddings (not Chroma's embedder)
+      #
+      # Chroma collections can carry an embedding function in
+      # their metadata — Chroma's term for what pikuri calls an
+      # {Embedder}. When configured, +add+ / +query+ accept raw
+      # text via +documents+ / +query_texts+ and Chroma embeds
+      # server-side. We deliberately don't use this: pikuri's
+      # +Embedder+ is the one source of truth for embedder
+      # choice, the provider-cliff visibility lives in pikuri's
+      # config, and a parallel Chroma-side embedder config would
+      # split the truth without pikuri noticing (e.g. local
+      # embedder in pikuri + +OpenAIEmbeddingFunction+ in Chroma
+      # — every indexed document silently lands at OpenAI). We
+      # always send pre-computed +embeddings+; Chroma's
+      # collection embedder is never invoked.
+      #
+      # == Vector-dim contract diverges from InMemory
+      #
+      # +InMemory+ enforces vector-dim consistency client-side
+      # (locks on first upsert, raises +ArgumentError+ on
+      # mismatch). +Chroma+ enforces server-side — first upsert
+      # to a collection establishes the dim; mismatched
+      # subsequent upserts produce HTTP 4xx which propagates
+      # as +RuntimeError+. Different exception class, same
+      # loud-failure shape. Documented divergence; not worth
+      # parsing Chroma's error envelope to coerce to +ArgumentError+.
+      #
+      # == Lazy collection resolution
+      #
+      # +Backend::Chroma.new+ doesn't talk to the server. The
+      # first +#upsert+ / +#query+ / +#count+ call resolves
+      # (and creates if missing) the collection by name, caches
+      # the id, and uses it thereafter. +#delete_all+ drops the
+      # collection and clears the cached id; the next +#upsert+
+      # re-creates from scratch.
+      #
+      # == Cosine distance (matches InMemory)
+      #
+      # Collection is created with +hnsw.space: 'cosine'+.
+      # Chroma returns cosine *distance* (range +[0, 2]+ where
+      # +0+ = identical, +1+ = orthogonal); +#query+ converts
+      # to similarity via +1 - distance+ so the {Backend::Result}
+      # score has the same meaning across backends.
+      #
+      # == Metadata key normalization
+      #
+      # Chroma serializes through JSON, so Symbol metadata keys
+      # become Strings on round-trip. +#upsert+ converts the
+      # incoming {Chunk}'s +metadata+ keys to Strings before
+      # sending; +#query+ converts them back to Symbols on the
+      # way out, so the {Chunk} a caller pulls from a query
+      # looks identical to one stored in InMemory. +source+
+      # rides as a special metadata key (Chroma has no native
+      # +source+ concept).
+      #
+      # == Testing posture
+      #
+      # Specs use +Faraday::Adapter::Test+ stubs only — they
+      # verify "we send what we think we're sending" against
+      # the v2 API shape but don't catch real-Chroma protocol
+      # drift. Real-Chroma smoke testing is wired into the demo
+      # binary in a later phase. Targets Chroma 0.5.x+ (v2 API).
+      class Chroma
+        # @param host [String]
+        # @param port [Integer]
+        # @param collection [String] collection name in Chroma.
+        #   This is a Chroma-specific identifier, so it lives
+        #   here rather than on +VectorDb::Extension+ (where
+        #   it'd be a no-op for +Backend::InMemory+).
+        # @param tenant [String] Chroma v2 tenant; defaults to
+        #   Chroma's own default.
+        # @param database [String] Chroma v2 database; defaults
+        #   to Chroma's own default.
+        # @param connection [Faraday::Connection, nil] optional
+        #   dependency-injection point for tests.
+        # @return [Chroma]
+        # @raise [ArgumentError] on empty +host+ or empty
+        #   +collection+.
+        def initialize(host:, port:, collection:,
+                       tenant: 'default_tenant',
+                       database: 'default_database',
+                       connection: nil)
+          raise ArgumentError, 'host must be non-empty' if host.nil? || host.to_s.empty?
+          raise ArgumentError, 'collection must be non-empty' if collection.nil? || collection.to_s.empty?
+
+          @host = host
+          @port = port
+          @collection_name = collection
+          @tenant = tenant
+          @database = database
+          @collection_id = nil
+          @connection = connection || Faraday.new(url: "http://#{host}:#{port}") do |f|
+            f.request :json
+            f.response :json
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        # Insert-or-replace by +chunk.id+. Parallel arrays of
+        # equal length; raises on empty input or length mismatch
+        # (same contract as {InMemory}). Chroma server enforces
+        # vector-dim consistency; mismatched dims surface as
+        # +RuntimeError+ from a 4xx response (the InMemory
+        # backend raises +ArgumentError+ for the same case —
+        # documented divergence).
+        #
+        # @param chunks [Array<Chunk>]
+        # @param vectors [Array<Array<Float>>]
+        # @return [void]
+        # @raise [ArgumentError] on empty input or length mismatch.
+        # @raise [RuntimeError] on HTTP failure.
+        def upsert(chunks:, vectors:)
+          raise ArgumentError, 'upsert called with empty chunks/vectors' if chunks.empty?
+          if chunks.size != vectors.size
+            raise ArgumentError, "size mismatch: #{chunks.size} chunks vs #{vectors.size} vectors"
+          end
+
+          ensure_collection!
+
+          metadatas = chunks.map do |c|
+            # Serialize +source+ as a reserved key in Chroma's
+            # +metadata+; merge in the user's metadata Hash with
+            # keys stringified for JSON round-trip stability.
+            base = { 'source' => c.source }
+            c.metadata.each { |k, v| base[k.to_s] = v }
+            base
+          end
+
+          body = {
+            ids: chunks.map(&:id),
+            embeddings: vectors,
+            documents: chunks.map(&:text),
+            metadatas: metadatas
+          }
+
+          post_json("#{collection_path}/upsert", body)
+          nil
+        end
+
+        # k-NN query by cosine similarity. Returns at most
+        # +top_k+ {Backend::Result}s descending by score.
+        # +score+ is +1 - cosine_distance+ so the value matches
+        # {InMemory}'s cosine-similarity scale.
+        #
+        # @param vector [Array<Float>]
+        # @param top_k [Integer]
+        # @return [Array<Backend::Result>]
+        # @raise [ArgumentError] on non-positive +top_k+.
+        # @raise [RuntimeError] on HTTP failure.
+        def query(vector:, top_k:)
+          raise ArgumentError, "top_k must be positive (got #{top_k})" if top_k <= 0
+
+          # If we've never upserted, the collection doesn't
+          # exist yet — semantic answer is "no hits."
+          return [] if @collection_id.nil? && !collection_exists?
+
+          response_body = post_json("#{collection_path}/query", {
+                                      query_embeddings: [vector],
+                                      n_results: top_k,
+                                      include: %w[documents metadatas distances]
+                                    })
+
+          ids = (response_body['ids']       || [[]]).first || []
+          docs = (response_body['documents'] || [[]]).first || []
+          metas = (response_body['metadatas'] || [[]]).first || []
+          dists = (response_body['distances'] || [[]]).first || []
+
+          ids.each_with_index.map do |id, i|
+            meta = metas[i] || {}
+            # Pull +source+ back out of the metadata blob;
+            # symbolize the remaining keys for round-trip
+            # consistency with InMemory.
+            source = meta['source'] || ''
+            chunk_meta = {}
+            meta.each do |k, v|
+              next if k == 'source'
+
+              chunk_meta[k.to_sym] = v
+            end
+
+            chunk = Chunk.new(id: id, source: source, text: docs[i] || '', metadata: chunk_meta)
+            Result.new(chunk: chunk, score: 1.0 - dists[i].to_f)
+          end
+        end
+
+        # Drop the collection. Next +#upsert+ re-creates from
+        # scratch — that's the v1 nuke-and-reload reindex path
+        # the {Indexer} drives. No-op if no collection was ever
+        # created (consistent with {InMemory}'s clear-on-empty
+        # behaviour). 404 on the DELETE is treated as "already
+        # gone" — idempotent.
+        #
+        # @return [void]
+        def delete_all
+          return nil if @collection_id.nil? && !collection_exists?
+
+          response = @connection.delete(collection_path)
+          unless [200, 204, 404].include?(response.status)
+            raise "Backend::Chroma: DELETE #{collection_path} returned " \
+                  "HTTP #{response.status}: #{response.body.inspect}"
+          end
+          @collection_id = nil
+          nil
+        end
+
+        # @return [Integer] current chunk count. Zero before the
+        #   first +#upsert+.
+        def count
+          return 0 if @collection_id.nil? && !collection_exists?
+
+          response = @connection.get("#{collection_path}/count")
+          unless response.status == 200
+            raise "Backend::Chroma: GET #{collection_path}/count returned " \
+                  "HTTP #{response.status}: #{response.body.inspect}"
+          end
+
+          body = response.body
+          # Chroma v2 returns the count as a bare integer.
+          return body if body.is_a?(Integer)
+          return body['count'] if body.is_a?(Hash) && body['count'].is_a?(Integer)
+
+          raise "Backend::Chroma: count response was not an Integer (got #{body.inspect})"
+        end
+
+        private
+
+        def collections_path
+          "/api/v2/tenants/#{@tenant}/databases/#{@database}/collections"
+        end
+
+        def collection_path
+          raise 'Backend::Chroma: collection_id not yet resolved' unless @collection_id
+
+          "#{collections_path}/#{@collection_id}"
+        end
+
+        # Idempotent get-or-create against Chroma. Sets
+        # +@collection_id+ on success. Returns the id String.
+        def ensure_collection!
+          return @collection_id if @collection_id
+
+          body = post_json(collections_path, {
+                             name: @collection_name,
+                             configuration: { hnsw: { space: 'cosine' } },
+                             get_or_create: true
+                           })
+
+          id = body.is_a?(Hash) ? body['id'] : nil
+          raise "Backend::Chroma: collection-create response missing 'id' (got #{body.inspect})" unless id
+
+          @collection_id = id
+        end
+
+        # Probe whether the collection exists without creating
+        # it — used by +#query+ / +#count+ / +#delete_all+ to
+        # short-circuit when the user queries before any upsert
+        # has happened. Side-effect: caches +@collection_id+
+        # when found.
+        def collection_exists?
+          response = @connection.get(collections_path)
+          unless response.status == 200
+            raise "Backend::Chroma: GET #{collections_path} returned " \
+                  "HTTP #{response.status}: #{response.body.inspect}"
+          end
+
+          list = response.body
+          return false unless list.is_a?(Array)
+
+          match = list.find { |c| c.is_a?(Hash) && c['name'] == @collection_name }
+          return false unless match
+
+          @collection_id = match['id']
+          true
+        rescue Faraday::Error => e
+          raise "Backend::Chroma: #{e.class.name.split('::').last} " \
+                "calling #{collections_path}: #{e.message}"
+        end
+
+        # Tiny JSON-POST helper shared by upsert / query /
+        # ensure_collection. Centralises the error-shape and
+        # Faraday::Error wrapping.
+        def post_json(path, body)
+          response = @connection.post(path) do |req|
+            req.headers['Content-Type'] = 'application/json'
+            req.body = body
+          end
+
+          unless [200, 201].include?(response.status)
+            raise "Backend::Chroma: POST #{path} returned " \
+                  "HTTP #{response.status}: #{response.body.inspect}"
+          end
+
+          response.body
+        rescue Faraday::Error => e
+          raise "Backend::Chroma: #{e.class.name.split('::').last} " \
+                "calling #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/vector_db/backend/in_memory.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module VectorDb
+    module Backend
+      # Pure-Ruby vector store. The educational default backend;
+      # IDEAS.md §"Vector DB / RAG" frames it as the "small enough
+      # to audit" first stop the demo + guide walk through before
+      # promoting users to +Chroma+ for persistence.
+      #
+      # == What it does
+      #
+      # Holds an in-memory Hash from chunk id to +[Chunk, vector]+;
+      # +#query+ computes cosine similarity against every stored
+      # vector, sorts descending, returns the top-k as
+      # +Backend::Result+ instances. O(n) per query, where n is
+      # the number of stored chunks. Fine for thousands of chunks
+      # (a personal notes folder, a single product's docs); slow
+      # for millions (a full corporate knowledge base — that's the
+      # +Chroma+ use case).
+      #
+      # == What it deliberately doesn't do
+      #
+      # * **No persistence.** RAM-only, intentional — the user who
+      #   wants persistence picks +Chroma+. Reloads from sources on
+      #   every boot, which makes the in-memory backend the natural
+      #   teaching shape: the same code path the demo binary walks
+      #   on startup is the one the user inspects when they're
+      #   learning what "indexing" actually means.
+      # * **No approximate search.** Exhaustive scan. Approximate
+      #   nearest neighbor (HNSW, IVF) adds complexity that doesn't
+      #   teach anything additional once the cosine math is clear.
+      # * **No thread safety.** {Indexer} runs single-threaded
+      #   during a boot or reindex; {Search} calls +#query+ from
+      #   the agent's main thread. No concurrent access today.
+      #
+      # == Cosine, not dot product
+      #
+      # Some embedders return pre-normalized vectors (text-embedding-3,
+      # most sentence-transformers); others don't. Cosine normalizes
+      # at compute time, so the backend works regardless of whether
+      # the embedder did. The readable two-pass form below (compute
+      # dot + magnitudes separately) is intentional over the
+      # single-loop micro-optimization — this is the file the
+      # newcomer reads to understand what's happening.
+      class InMemory
+        # @return [InMemory]
+        def initialize
+          # id (String) → [Chunk, vector (Array<Float>)]
+          @entries = {}
+          # Dimension of every stored vector. +nil+ before the first
+          # +#upsert+; locked to the dim of the first vector seen and
+          # enforced for every subsequent +#upsert+ + +#query+ — see
+          # the Backend protocol's "Vector-dim contract" yardoc.
+          @dim = nil
+        end
+
+        # Insert-or-replace by +chunk.id+. Parallel arrays of
+        # equal length; raises on empty input or length mismatch.
+        # Vector dimension is locked at first upsert; raises on
+        # any subsequent vector of a different dim.
+        #
+        # @param chunks [Array<Chunk>]
+        # @param vectors [Array<Array<Float>>]
+        # @return [void]
+        # @raise [ArgumentError] on empty input, length mismatch,
+        #   or vector-dim mismatch.
+        def upsert(chunks:, vectors:)
+          raise ArgumentError, 'upsert called with empty chunks/vectors' if chunks.empty?
+          if chunks.size != vectors.size
+            raise ArgumentError, "size mismatch: #{chunks.size} chunks vs #{vectors.size} vectors"
+          end
+
+          expected = @dim || vectors.first.size
+          vectors.each_with_index do |v, i|
+            next if v.size == expected
+
+            raise ArgumentError, "vector #{i} has dim #{v.size}, expected #{expected}"
+          end
+          @dim ||= expected
+
+          chunks.zip(vectors).each { |chunk, vector| @entries[chunk.id] = [chunk, vector] }
+          nil
+        end
+
+        # Cosine-similarity nearest neighbor search. Returns the
+        # top-k {Backend::Result}s in descending score order;
+        # empty array when the store has no entries.
+        #
+        # @param vector [Array<Float>] query vector; must match
+        #   the stored vector dim.
+        # @param top_k [Integer] number of results to return;
+        #   must be positive.
+        # @return [Array<Backend::Result>]
+        # @raise [ArgumentError] on +top_k+ <= 0 or query-vector
+        #   dim mismatch.
+        def query(vector:, top_k:)
+          raise ArgumentError, "top_k must be positive (got #{top_k})" if top_k <= 0
+          return [] if @entries.empty?
+
+          if vector.size != @dim
+            raise ArgumentError, "query vector dim #{vector.size}, stored dim #{@dim}"
+          end
+
+          scored = @entries.values.map do |chunk, stored|
+            Result.new(chunk: chunk, score: cosine(vector, stored))
+          end
+          scored.sort_by { |r| -r.score }.first(top_k)
+        end
+
+        # Drop every stored chunk. Used by the v1 nuke-and-reload
+        # reindex flow; the embedder dim lock is also released so
+        # a reindex with a different embedder model starts clean.
+        #
+        # @return [void]
+        def delete_all
+          @entries.clear
+          @dim = nil
+          nil
+        end
+
+        # @return [Integer] current chunk count.
+        def count
+          @entries.size
+        end
+
+        private
+
+        # Cosine similarity. Two-pass form is the readable shape;
+        # micro-optimizing into a single loop saves an array
+        # traversal but obscures what's happening for the reader
+        # who's here to learn how a vector store works.
+        #
+        # @param a [Array<Float>]
+        # @param b [Array<Float>]
+        # @return [Float] cosine in +[-1.0, 1.0]+, or +0.0+ if
+        #   either vector is zero (degenerate but valid input).
+        def cosine(a, b)
+          dot = a.zip(b).sum { |x, y| x * y }
+          mag_a = Math.sqrt(a.sum { |x| x * x })
+          mag_b = Math.sqrt(b.sum { |x| x * x })
+          return 0.0 if mag_a.zero? || mag_b.zero?
+
+          dot / (mag_a * mag_b)
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/vector_db/backend/result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module VectorDb
+    module Backend
+      # A single query hit: the {Chunk} that matched + its cosine
+      # similarity score. Returned in descending-score order from
+      # any backend's +#query+ method.
+      #
+      # == Fields
+      #
+      # * +chunk+ — the stored {Chunk} (id, text, metadata).
+      # * +score+ — cosine similarity as +Float+, range
+      #   +[-1.0, 1.0]+. For typical sentence-embedder vectors
+      #   (all-positive component dimensions after the softmax /
+      #   normalization most models bake in) scores stay in
+      #   +[0.0, 1.0]+ in practice. 1.0 is exact match; 0.0 is
+      #   orthogonal.
+      #
+      # == Citation
+      #
+      # {Search} formats hits for the LLM as
+      # +result.chunk.source+ (the citation — relative path, URL,
+      # or doc ID — see {Chunk}'s +source+ field) +
+      # +result.chunk.text+ (the snippet) + the score. The +id+
+      # field is opaque and never surfaced; the +metadata+ Hash
+      # carries optional extras like offset / page / anchor for
+      # callers that want to deep-link.
+      #
+      # The +score+ is cosine *as returned by a backend's
+      # +#query+*. {Search} substitutes the reranker's relevance
+      # score here (via +Data#with+) before formatting when a
+      # reranker reorders the candidates, so a surfaced score is
+      # cosine only in vector-only mode — see {Search}'s
+      # "Which score is shown" section.
+      #
+      # == Why a Data.define
+      #
+      # Same convention as {Chunk}. A tuple +[chunk, score]+ or
+      # a +{chunk:, score:}+ Hash would work at runtime but
+      # +result.chunk+ / +result.score+ reads cleaner at call
+      # sites, and value-equality is occasionally useful in specs.
+      Result = Data.define(:chunk, :score)
+    end
+  end
+end