brainchat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '09e175edc9c5ee8494be30f5ae64384d38e493c029e212e363cb6ffea74eb435'
+  data.tar.gz: 75d5889ecf72f543c622585c49406b8066d566747aff824a565a4f0cb3762348
+SHA512:
+  metadata.gz: '09e02f48285304b6e142e0f25b41f238874bb183e3dbd202485332a1d8a9343b8e0a6bbca750612df660d994329acf4edc32fdaf402b8cb94f664688a29342b1'
+  data.tar.gz: ac64f712e98f66a072c5a133880f0a54296ce754f95d16a41d288e683268a554e9dc32f5ed29502fb72bc448c8634fa0d1fa788095ba07ce006b7e0792e0519b

data/.ruby-version

@@ -0,0 +1 @@
+3.4.10

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] - 2026-07-27
+
+- Initial release: `brainchat ask QUESTION` answers from a knowledge-brain
+  vault with citations. Retrieval shells out to the hitgate `rag-query` CLI in
+  JSON mode (argv-array via `Open3.capture3`, no shell interpolation); the chat
+  is RubyLLM with retrieved chunks injected as numbered context and cited as
+  `[n]` in the reply, with a `[n] -> path:lines` sources list printed after the
+  answer.
+- Streaming by default; `--no-stream` prints the complete answer at once.
+- Provider configuration via `--model` / `--provider` / `--assume-model-exists`
+  and the `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_API_BASE`
+  environment variables. `--provider ollama` needs no setup.
+- Retriever honors `BRAINCHAT_RAG_QUERY_BIN` and passes `RAG_*` index
+  configuration through to `rag-query`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucas Santana
+
+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,132 @@
+# brainchat
+
+[![CI](https://github.com/LucasSantana-Dev/brainchat/actions/workflows/main.yml/badge.svg)](https://github.com/LucasSantana-Dev/brainchat/actions/workflows/main.yml)
+[![Ruby >= 3.2](https://img.shields.io/badge/ruby-%3E%3D%203.2-red)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+**Chat with your knowledge base from the terminal, with citations that resolve to real files.**
+brainchat is a Ruby AI CLI that answers questions over a "knowledge-brain" vault (notes, ADRs,
+plans, commit history, docs) and labels every claim with the exact chunk it came from.
+
+```
+$ brainchat ask "what did we decide about hitgate caveat timing"
+
+Ship the two-channel honesty check first, then the self-indexed caveat [1][2]. The
+rationale: publishing the caveat first would anchor the evaluation story on a limitation
+with no third-party evidence behind it [1].
+
+Sources:
+  [1] /vault/knowledge-brain/docs/adr/0012-caveat-investment-timing.md:1-34 (repo-docs/hitgate)
+  [2] /vault/knowledge-brain/memory/caveat-timing-note.md:3-9 (memory/knowledge-brain)
+```
+
+## How it works
+
+brainchat deliberately does **not** reimplement retrieval. It composes two tools that each do
+one thing well:
+
+1. Your question goes to [`rag-query`](https://github.com/LucasSantana-Dev/hitgate), the
+   hybrid BM25 + cosine retrieval CLI that hitgate's regression gate benchmarks. brainchat
+   shells out with `Open3.capture3` and an argv-array (never a shell string) and treats the
+   JSON output as the retrieval contract.
+2. The retrieved chunks are injected into a [RubyLLM](https://rubyllm.com) chat as numbered
+   context. The system prompt requires `[n]` citations, and the CLI prints the
+   `[n] -> path:lines` mapping after the answer, so every citation resolves to a file and
+   line range you can open.
+
+Provider-agnostic: Anthropic, OpenAI, or fully local with Ollama.
+
+## Requirements
+
+- Ruby >= 3.2
+- The `rag-query` executable from [hitgate](https://github.com/LucasSantana-Dev/hitgate) on
+  your `PATH` (or point `BRAINCHAT_RAG_QUERY_BIN` at it), plus an indexed vault. `rag-query`
+  is configured through its own `RAG_*` environment variables (e.g. `RAG_INDEX_DIR`), which
+  brainchat passes straight through.
+  - **`--scope-repo all` needs hitgate at or after
+    [#134](https://github.com/LucasSantana-Dev/hitgate/pull/134).** Earlier versions turned the
+    `all` sentinel into "no preference", which re-enabled cwd auto-scoping; since hitgate's
+    source roots default to the working directory, every query got scoped to a repo named after
+    whatever directory you were standing in and came back empty with exit 0. If `brainchat ask`
+    finds nothing in an index you know is populated, check this first.
+- A provider: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, or a local Ollama.
+
+## Install
+
+Not on RubyGems yet. Build from source:
+
+```bash
+git clone https://github.com/LucasSantana-Dev/brainchat
+cd brainchat && bin/setup
+gem build brainchat.gemspec && gem install ./brainchat-0.1.0.gem
+```
+
+Or run it without installing: `bundle exec exe/brainchat ask "..."`.
+
+## Usage
+
+```bash
+brainchat ask "what did we decide about hitgate caveat timing"
+brainchat ask "how does the reranker fall back" --top 8 --scope-repo all
+brainchat ask "..." --provider ollama --model qwen3:4b --assume-model-exists  # fully local
+brainchat ask "..." --no-stream    # print the answer only when complete
+brainchat ask "..." --rerank       # cross-encoder reranker (slower, better ranking)
+```
+
+| Flag | Purpose |
+|---|---|
+| `--top N` | number of chunks to retrieve (default 5) |
+| `--scope-repo a,b` | restrict retrieval to named repos, or `all` to disable cwd scoping |
+| `--rerank` | enable the cross-encoder reranker (default: fast mode) |
+| `--provider NAME` | `anthropic`, `openai`, `ollama` |
+| `--model ID` | model id (default: RubyLLM's configured default) |
+| `--assume-model-exists` | skip model-registry validation, needed for local Ollama models |
+| `--no-stream` | print the complete answer at once instead of streaming |
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic provider key |
+| `OPENAI_API_KEY` | OpenAI provider key |
+| `OLLAMA_API_BASE` | Ollama endpoint (default `http://localhost:11434/v1`) |
+| `BRAINCHAT_RAG_QUERY_BIN` | path to the `rag-query` executable (default: `rag-query` on `PATH`) |
+| `RAG_INDEX_DIR` and other `RAG_*` | hitgate index configuration, passed through to `rag-query` |
+
+## Under the hood
+
+Built around Ruby idioms, not ported line-for-line from anything:
+
+- **`Open3.capture3` with an argv-array, never a shell string.** The question travels as one
+  bare argv entry, so a query containing `$(...)`, backticks or `;` is inert data. The spec
+  suite proves this with a shell-injection marker test that fails if the query is ever
+  interpolated into a shell.
+- **`Data.define` for the `Chunk` value object**: immutable, keyword-constructed, with a
+  `#location` helper that renders `path:start-end` (or bare `path` for line-less chunks like
+  git commits).
+- **RubyLLM wired explicitly.** RubyLLM 1.16 reads no provider env vars on its own, so
+  `Chat.configure` feeds it `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_API_BASE` itself.
+- **Streaming by default** via `chat.ask(prompt) { |chunk| ... }`; `--no-stream` prints the
+  complete answer at once.
+- **Thor** for CLI dispatch.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake   # rspec + rubocop
+```
+
+Specs stub both boundaries: the retriever is tested against a fixture of real `rag-query`
+JSON output (no subprocess), and the chat against a stubbed RubyLLM (no network).
+
+## Related projects
+
+- [hitgate](https://github.com/LucasSantana-Dev/hitgate): the retrieval engine and regression
+  gate brainchat queries.
+- [leakless](https://github.com/LucasSantana-Dev/leakless): rule-driven secret scanner with
+  redact-always AI triage, same Ruby-idiom-first approach.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/brainchat

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "brainchat"
+
+Brainchat::CLI.start(ARGV)

data/lib/brainchat/chat.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Brainchat
+  # Answers a question with an LLM, using retrieved knowledge-brain chunks as
+  # the only context. Chunks are numbered in the prompt and the model is asked
+  # to cite them as [n]; the CLI prints the [n] -> path:lines mapping after the
+  # answer, so every citation is resolvable to a file.
+  module Chat
+    # Ollama's conventional local endpoint, so --provider ollama needs no setup.
+    OLLAMA_DEFAULT_BASE = "http://localhost:11434/v1"
+
+    # A missing API key or an unknown model id raise off a different branch of
+    # RubyLLM's hierarchy than provider/HTTP faults, and they are the two most
+    # likely failures here, so both branches are caught.
+    FAILURES = [RubyLLM::Error, RubyLLM::ConfigurationError,
+                RubyLLM::ModelNotFoundError, Faraday::Error].freeze
+
+    SYSTEM_PROMPT = <<~PROMPT
+      You answer questions about the user's knowledge-brain: a vault of notes,
+      ADRs, plans, commit history and docs, retrieved for you by a hybrid
+      BM25 + cosine search. The retrieved chunks are numbered and included in
+      the user's message.
+
+      Answer only from those chunks. When the chunks do not contain the answer,
+      say so plainly instead of guessing. Cite every claim with the chunk
+      number in square brackets, e.g. [1] or [2][3]. Keep the answer tight;
+      quote file paths only via the citation numbers.
+    PROMPT
+
+    module_function
+
+    # Asks `question` with `chunks` as context. Streams each content delta to
+    # `on_chunk` when given. Returns the final RubyLLM::Message.
+    def call(question, chunks, on_chunk: nil, **chat_options)
+      configure
+      chat = RubyLLM.chat(**chat_options.compact)
+                    .with_instructions(SYSTEM_PROMPT)
+      if on_chunk
+        chat.ask(prompt_for(question, chunks)) { |chunk| on_chunk.call(chunk.content) }
+      else
+        chat.ask(prompt_for(question, chunks))
+      end
+    rescue *FAILURES => e
+      raise Error, "chat failed: #{e.class}: #{e.message}"
+    end
+
+    # RubyLLM reads no provider credentials from the environment on its own,
+    # and a CLI has nowhere else to get them.
+    def configure
+      RubyLLM.configure do |config|
+        config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+        config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+        config.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", OLLAMA_DEFAULT_BASE)
+      end
+    end
+
+    # Chunks go over as a numbered list; the citation number the model emits is
+    # the position in this list, and the CLI prints the same numbering.
+    def prompt_for(question, chunks)
+      body = chunks.each_with_index.map do |chunk, index|
+        <<~CHUNK
+          [#{index + 1}] #{chunk.location} (#{chunk.source_type}/#{chunk.repo})
+          #{chunk.text}
+        CHUNK
+      end.join("\n")
+
+      <<~PROMPT
+        Retrieved chunks:
+
+        #{body}
+
+        Question: #{question}
+      PROMPT
+    end
+  end
+end

data/lib/brainchat/cli.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "retriever"
+require_relative "chat"
+
+module Brainchat
+  # Thor command-line interface. `ask` retrieves chunks via rag-query and
+  # streams the cited answer to stdout.
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    desc "ask QUESTION", "answer a question from the knowledge-brain, citing retrieved chunks"
+    method_option :top,
+                  type: :numeric,
+                  default: Retriever::DEFAULT_TOP,
+                  desc: "number of chunks to retrieve"
+    method_option :scope_repo,
+                  type: :string,
+                  desc: "comma-separated repo names to search, or 'all' to disable cwd scoping"
+    method_option :rerank,
+                  type: :boolean,
+                  default: false,
+                  desc: "enable the cross-encoder reranker (slower, better ranking)"
+    method_option :model,
+                  type: :string,
+                  desc: "model id (default: RubyLLM's configured default)"
+    method_option :provider,
+                  type: :string,
+                  desc: "provider, e.g. anthropic, openai, ollama"
+    method_option :assume_model_exists,
+                  type: :boolean,
+                  default: false,
+                  desc: "skip model-registry validation, needed for local Ollama models"
+    method_option :no_stream,
+                  type: :boolean,
+                  default: false,
+                  desc: "print the answer only once it is complete"
+    def ask(question)
+      chunks = retrieve(question)
+      answer(question, chunks)
+      print_sources(chunks)
+    rescue Error => e
+      warn e.message
+      exit 1
+    end
+
+    no_commands do
+      def retrieve(question)
+        chunks = Retriever.call(question,
+                                top: options[:top],
+                                scope_repo: options[:scope_repo],
+                                fast: !options[:rerank])
+        return chunks unless chunks.empty?
+
+        raise Error, "No chunks retrieved for this question. Is the knowledge-brain indexed " \
+                     "(RAG_INDEX_DIR) and is `rag-query` working?"
+      end
+
+      def answer(question, chunks)
+        on_chunk = options[:no_stream] ? nil : ->(content) { print content }
+        message = Chat.call(question, chunks,
+                            on_chunk:,
+                            model: options[:model],
+                            provider: options[:provider]&.to_sym,
+                            assume_model_exists: options[:assume_model_exists])
+        # In streaming mode the deltas already went to stdout; in --no-stream
+        # mode nothing has been printed yet.
+        puts(options[:no_stream] ? message.content : "")
+      end
+
+      def print_sources(chunks)
+        puts "\nSources:"
+        chunks.each_with_index do |chunk, index|
+          puts "  [#{index + 1}] #{chunk.location} (#{chunk.source_type}/#{chunk.repo})"
+        end
+      end
+    end
+  end
+end

data/lib/brainchat/retriever.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Brainchat
+  # Retrieves knowledge-brain chunks by shelling out to the hitgate `rag-query`
+  # CLI in its JSON output mode:
+  #
+  #   rag-query --top N --format json [--scope-repo all] [--fast] "<query>"
+  #
+  # stdout is a pure JSON array of chunks (warnings and model-load progress go
+  # to stderr), each shaped:
+  #
+  #   { "rank", "rrf", "cos", "bm25", "reranked", "source_type", "repo",
+  #     "language", "symbol", "path", "start_line", "end_line", "text" }
+  #
+  # The query and every flag travel as separate argv entries through
+  # Open3.capture3 — no shell is ever involved, so a query containing
+  # metacharacters (`$(...)`, backticks, `;`) is inert data, not a command.
+  module Retriever
+    # One retrieved chunk. `Data.define` gives an immutable value object with
+    # free keyword construction, matching the Finding idiom in leakless.
+    Chunk = Data.define(:rank, :source_type, :repo, :symbol, :path, :start_line, :end_line, :text) do
+      # "path:12-40", or just "path" for chunks without line information
+      # (git-commit chunks carry start_line/end_line of 0).
+      def location
+        return path.to_s if start_line.to_i.zero? && end_line.to_i.zero?
+
+        "#{path}:#{start_line}-#{end_line}"
+      end
+    end
+
+    DEFAULT_TOP = 5
+
+    module_function
+
+    # Returns an array of Chunk, empty when the index has no matches.
+    def call(query, top: DEFAULT_TOP, scope_repo: nil, fast: true, bin: default_bin)
+      stdout, stderr, status = Open3.capture3(*argv(bin, query, top:, scope_repo:, fast:))
+      raise Error, "rag-query failed (exit #{status.exitstatus}): #{stderr.strip}" unless status.success?
+
+      parse(stdout)
+    rescue Errno::ENOENT
+      raise Error, "`#{bin}` was not found on PATH. Install hitgate " \
+                    "(https://github.com/LucasSantana-Dev/hitgate) or point " \
+                    "BRAINCHAT_RAG_QUERY_BIN at a rag-query executable."
+    end
+
+    def argv(bin, query, top:, scope_repo:, fast:)
+      args = [bin, "--top", top.to_s, "--format", "json"]
+      args += ["--scope-repo", scope_repo] if scope_repo
+      args << "--fast" if fast
+      args << query
+    end
+
+    def parse(stdout)
+      rows = JSON.parse(stdout)
+      unless rows.is_a?(Array) && rows.all?(Hash)
+        raise Error, "rag-query returned unexpected JSON (expected an array of chunks)"
+      end
+
+      rows.map { |row| chunk_from(row) }
+    rescue JSON::ParserError => e
+      raise Error, "rag-query did not return valid JSON: #{e.message}"
+    end
+
+    def chunk_from(row)
+      Chunk.new(rank: row["rank"],
+                source_type: row["source_type"],
+                repo: row["repo"],
+                symbol: row["symbol"],
+                path: row["path"],
+                start_line: row["start_line"],
+                end_line: row["end_line"],
+                text: row["text"])
+    end
+
+    def default_bin
+      ENV.fetch("BRAINCHAT_RAG_QUERY_BIN", "rag-query")
+    end
+  end
+end

data/lib/brainchat/version.rb

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

data/lib/brainchat.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "brainchat/version"
+
+module Brainchat
+  class Error < StandardError; end
+end
+
+require_relative "brainchat/cli"

data/sig/brainchat.rbs

@@ -0,0 +1,14 @@
+module Brainchat
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  module Retriever
+    def self.call: (String query, ?top: Integer, ?scope_repo: String?, ?fast: bool, ?bin: String) -> Array[Chunk]
+  end
+
+  module Chat
+    def self.call: (String question, Array[Retriever::Chunk] chunks, ?on_chunk: ^(String) -> void, **untyped chat_options) -> untyped
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: brainchat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucas Santana
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-07-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A small Ruby CLI that answers questions about a knowledge-brain vault.
+  Retrieval shells out to the hitgate `rag-query` CLI (JSON mode, argv-array, no shell
+  interpolation); the chat is RubyLLM, with retrieved chunks injected as context and
+  cited in the reply.
+email:
+- lucas.diassantana@gmail.com
+executables:
+- brainchat
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/brainchat
+- lib/brainchat.rb
+- lib/brainchat/chat.rb
+- lib/brainchat/cli.rb
+- lib/brainchat/retriever.rb
+- lib/brainchat/version.rb
+- sig/brainchat.rbs
+homepage: https://github.com/LucasSantana-Dev/brainchat
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/LucasSantana-Dev/brainchat
+  source_code_uri: https://github.com/LucasSantana-Dev/brainchat/tree/main
+  changelog_uri: https://github.com/LucasSantana-Dev/brainchat/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Chat over a knowledge-brain vault from the terminal.
+test_files: []